Вебхук

HTTP-запрос POST, который платформа отправляет на ваш сервер, когда что-то меняется, чтобы ваша система узнала о событии без постоянных опросов API.

#Как это работает в CryptoLike

CryptoLike отправляет подписанное JSON-событие на ваш адрес всякий раз, когда меняется состояние платежа, депозита или выплаты, — всего 21 тип событий, например invoice.paid, invoice.underpaid, invoice.expired, deposit.confirmed и withdrawal.completed. Добавьте endpoint в кабинете («Разработчикам» → «Вебхуки» → «Добавить эндпоинт») или запросом POST /v1/webhooks/endpoints: адрес https:// на публичном хосте, типы событий или * и секрет.

В каждом запросе есть заголовки X-Event-Id, X-Event-Type, X-Timestamp и X-Signature, а в теле — event_id, type, created_at и data. Ответьте статусом 2xx в течение 10 секунд. Иначе доставка повторяется через 1 мин, 5 мин, 15 мин, 1 ч, 6 ч и 24 ч — 7 попыток, около 31 часа, — после чего помечается как исчерпанная; повторить её можно в кабинете: «Разработчикам» → «Вебхуки» → «Доставки» → «Повторить».

Доставка — «хотя бы один раз», поэтому одно событие может прийти дважды с тем же event_id: сохраняйте его и пропускайте повторы. События одного платежа могут прийти не по порядку — ориентируйтесь на created_at и status в data. Кнопка отправки тестового события в кабинете шлёт подписанный ping на один endpoint. Проверяйте каждый запрос — см. подпись вебхука.

#Пример

Так выглядит запрос вебхука CryptoLike; тело показано отформатированным для чтения, а байты, которые вы получите, могут отличаться порядком ключей и пробелами. Разбирайте тело как JSON, а подпись проверяйте по сырым байтам ровно в том виде, в каком они пришли, и только потом сохраняйте событие:

POST /your/path HTTP/1.1
Content-Type: application/json
X-Event-Id: 6f1c2c1e-3b2a-4d5e-8f90-1234567890ab
X-Event-Type: invoice.paid
X-Timestamp: 1700000000
X-Signature: sha256=788e60a2141669b4c7616c1c616fefb8ec38df0948fba19c6f4e48c616e46c21

{"event_id":"6f1c2c1e-3b2a-4d5e-8f90-1234567890ab","type":"invoice.paid","created_at":"2023-11-14T22:13:20Z","data":{"invoice":{"id":"0e8c9a4b-1111-4222-8333-444455556666","status":"paid"}}}