Справочник вебхуков

События, payload, заголовки подписи, лесенка ретраев 1м→12ч и правила идемпотентности.

Всё о получении событий ZeroKYC Pay: каталог событий, форма payload, заголовки подписи, лесенка ретраев и правила идемпотентности.

События

Событие	Когда срабатывает
`payment.detected`	Найдена транзакция, соответствующая инвойсу (мемпул или ранние подтверждения)
`payment.confirmed`	Достигнуто нужное число подтверждений — сигнал «отгружать товар»
`payment.underpaid`	Наблюдаемая сумма < требуемой − `amount_tolerance`; решение за вами
`invoice.expired`	TTL истёк без валидного платежа
`invoice.canceled`	Инвойс отменён до оплаты
`payout.sent` / `payout.failed`	Транзитный свип на адрес выплат прошёл / не прошёл

Мультивариантные инвойсы (payment_currency=any) подтверждаются по первому валидному платежу; остальные варианты закрываются автоматически.

Payload

{
"id": "evt_5c1a...",
"type": "payment.confirmed",
"created_at": "2026-09-06T14:02:33Z",
"data": {
  "invoice_id": "inv_9f2k...",
  "order_id": "order-1042",
  "asset": "TON",
  "network": "ton",
  "amount_paid": "9.81",
  "paid_amount_usd": "49.00",
  "tx_hash": "9d24...",
  "confirmations": 1,
  "status": "confirmed"
}
}

id глобально уникален для события — сохраняйте его и дедуплицируйте.
order_id повторяет то, что вы отправили при создании; это ваш ключ соединения.
Переплаты подтверждаются штатно: amount_paid — наблюдаемая правда.

Подпись

Каждая доставка содержит:

X-ZKP-Signature: t=<unix seconds>,v1=<hex hmac-sha256>

Подпись — {timestamp}.{raw_body} секретом endpoint'а. Проверяйте, прежде чем доверять, — полные примеры Node/PHP/Python в проверке HMAC. Временное окно — 5 минут.

Доставка и ретраи

Попытка	Задержка
1	сразу
2	1 минута
3	5 минут
4	30 минут
5	2 часа
6	12 часов → затем `failed`

Доставка считается успешной при любом 2xx в течение нескольких секунд.
После исчерпания лесенки событие помечается failed; ручной retry доступен в кабинете (Вебхуки → журнал доставок) или по инвойсу (Инвойсы → retry вебхука).
Endpoint настраивается и ротируется в разделе Вебхуки: кнопка test-event отправляет подписанный ping, который можно проверить end-to-end.

Правила идемпотентности для потребителя

Сохраняйте event.id и пропускайте дубликаты — доставка at-least-once означает, что одно событие может прийти больше раза.
Считайте вебхуки подсказками, а не источником истины: GET /v1/invoices/{id} всегда даёт авторитетное состояние.
Rescan-задача перепроверяет все pending/detecting-инвойсы каждые 10 минут, поэтому пропущенные события цепочки самолечатся — payment.confirmed может прийти заметно позже транзакции.
Реагируйте на payment.confirmed как на триггер исполнения; payment.detected используйте только для раннего фидбэка покупателю.