Вебхуки
Сервер отправляет POST на webhook_url приложения (задаётся в настройках приложения в кабинете). Смена уже заданного URL требует код 2FA, если 2FA включена, и вступает в силу через час: на email аккаунта приходит письмо со ссылкой отмены. Первая установка URL применяется сразу.
Типы событий
update_type | Когда | payload |
|---|---|---|
invoice_paying | Платёж найден в блоке | инвойс + confirmations: 0, required_confirmations, txid |
invoice_paid | Инвойс оплачен (paid или overpaid). Включено всегда | инвойс + txid |
invoice_partially_paid | Подтверждена часть суммы | инвойс + txid |
invoice_expired | Срок истёк | инвойс |
invoice_canceled | Отменён через API или кабинет | инвойс |
payment_late | Платёж на истёкший инвойс | инвойс + txid + deposit |
payment_unexpected | Чужая монета или платёж на закрытый инвойс | инвойс + txid + deposit |
withdrawal_completed | Вывод подтверждён: все его переводы | вывод, txid и txids заполнены |
withdrawal_failed | Вывод отклонён сетью или оператором | вывод с error |
test | POST /webhooks/test или кнопка в кабинете. Включено всегда | {"message": "Тестовый вебхук Paylane"} |
«Инвойс» и «вывод» здесь имеют те же поля, что ответы GET /invoices/{id} (без transactions) и GET /withdrawals/{id}. Какие события получать, выбирается в настройках приложения. Новое приложение подписано на все, invoice_paid и test отключить нельзя.
Тело запроса
Для удобства JSON выше отформатирован. На проводе тело компактное, ключи отсортированы, кириллица не экранируется.
Заголовки
| Заголовок | Значение |
|---|---|
Content-Type | application/json |
Paylane-Signature | Подпись, hex |
Paylane-Signature-Next | Только 24 часа после смены секрета в кабинете: подпись новым секретом. Основные заголовки в это время подписаны старым |
Paylane-Timestamp | Время этой попытки доставки, unix-секунды |
Paylane-Signature-V2 | Подпись строки timestamp + "." + тело, тот же алгоритм и ключ. Защищает от повтора перехваченного запроса |
Paylane-Signature-V2-Next | Как Paylane-Signature-Next, для подписи с временем |
User-Agent | Paylane-Webhooks/1 |
Доставка
- Успех: ответ 2xx за 10 секунд. Тело ответа не читается, сохраняются только первые 1 КБ для журнала.
- Любой другой ответ, редирект (редиректы не выполняются), таймаут или ошибка соединения означают неудачу.
- 7 попыток: сразу, затем через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч после предыдущей неудачи, всего около 33 часов. После седьмой неудачи событие получает статус
failed. В журнале вебхуков кабинета видны все попытки, там же кнопка повтора. - Порядок: события одного приложения доставляются по очереди. Пока раннее событие не доставлено и у него меньше 3 попыток (около 6 минут), следующие ждут. После третьей неудачи оно повторяется по своему расписанию, а очередь идёт дальше: при коротком сбое порядок сохраняется, одно сломанное событие не держит остальные. Поэтому порядок прихода не гарантирован: опирайтесь на
update_idи статус в теле, а не на очерёдность. - Смена секрета: «Сгенерировать новый секрет» в настройках приложения. 24 часа
Paylane-Signatureподписан старым секретом,Paylane-Signature-Nextновым. Добавьте новый секрет на сервер, проверяя оба (SDK:parse_webhook(body, signature, [new_secret, old_secret])), затем «Завершить смену сейчас» или дождитесь конца срока. - Доставка «хотя бы один раз» (at-least-once). Одно событие может прийти больше одного раза: например, ваш сервер ответил 200 позже 10 секунд, соединение оборвалось после обработки, вы нажали «Повторить» в кабинете. Обработчик должен быть идемпотентным.
update_idрастёт монотонно в пределах приложения. Повторная доставка приходит с тем же , тем же телом и тем же (это время события, а не попытки). Дедуплицируйте по : сохраните обработанные id и отвечайте 200 на повтор, ничего не делая.