Вебхуки криптоплатежей: проверка подписи и повторные доставки

Вебхук — это запрос, который CryBit отправляет на ваш сервер, когда счёт меняет состояние. Это самый надёжный способ узнать об оплате заказа. Но это и публичный адрес, на который может писать кто угодно. Проверяйте каждый запрос, прежде чем действовать.

Что вы получаете

Запрос — POST с JSON-телом. Название события приходит в заголовке X-CryBit-Event, например payment.paid. События вы выбираете в настройках мерчанта: paid, expired, refunded, cancelled. URL вебхука задаётся у мерчанта, а не в запросе на создание счёта.

Проверьте подпись

В каждом вебхуке есть заголовок X-CryBit-Signature вида t=<unix-время>,v1=<hex>. Чтобы проверить его, возьмите t, соедините через точку с сырым телом запроса, посчитайте HMAC-SHA256 вашим секретом подписи и сравните результат с v1. Сравнивайте за постоянное время. Отклоняйте запрос, если t старше пяти минут. Секрет подписи каждого мерчанта — в настройках мерчанта, на вкладке «Интеграция». Без него подделать статус «оплачено» нельзя.

Считайте подпись по сырому телу ровно так, как оно пришло. Если сначала разобрать и снова собрать JSON, байты изменятся и проверка не пройдёт.

Отвечайте быстро, обрабатывайте безопасно

• Отвечайте статусом 2xx сразу после сохранения события, а тяжёлую работу делайте потом. CryBit ждёт около двенадцати секунд.
• Если вы не ответили, CryBit повторяет с растущими паузами: 15 секунд, 1 минута, 5, 15 и 30 минут, затем 2, 6 и 24 часа. Ответ 4xx, кроме 429, останавливает повторы.
• Сделайте обработку идемпотентной: одно и то же событие может прийти несколько раз. Используйте order_id или uuid счёта как ключ и игнорируйте повторную доставку.
• Не закрывайте заказ только по событию виджета в браузере. Оно нужно лишь для интерфейса.

Если вы по любой причине пропустили вебхуки, запросите статус счёта через GET /api/v1/payments/{uuid}. Статус — всегда источник истины.