Webhook-уведомления

Общие положения

Webhook позволяет Weelay отправить уведомление на backend продавца после важного события.

Главный сценарий — уведомить продавца, что счёт получил статус paid.

Webhook нужен, чтобы продавцу не приходилось постоянно вручную проверять статус счёта через API.

Webhook endpoint должен быть backend endpoint продавца. Нельзя использовать frontend URL или страницу, которая не умеет принимать POST запросы.

Когда отправляется webhook

Weelay отправляет webhook после события оплаты счёта.

Текущий основной event:

invoice.paid

Это событие означает, что счёт отмечен как оплаченный.

После получения и проверки такого webhook продавец может обновить свой заказ как оплаченный.

Webhook URL

Webhook URL задаётся в настройках проекта.

Webhook URL должен использовать HTTPS.

Пример:

https://example.com/weelay/webhook

Endpoint должен принимать POST запросы с JSON body.

Headers

Webhook-запрос от Weelay содержит служебные headers.

Основные headers:

• User-Agent;
• Content-Type;
• X-Weelay-Event;
• X-Weelay-Delivery;
• X-Weelay-Timestamp;
• X-Weelay-Signature.

Content-Type равен application/json.

X-Weelay-Event содержит event name, например invoice.paid.

X-Weelay-Delivery содержит идентификатор доставки webhook.

X-Weelay-Timestamp содержит Unix timestamp.

X-Weelay-Signature содержит подпись webhook.

Подпись webhook

Каждый webhook подписывается.

Header подписи имеет формат:

X-Weelay-Signature: t={timestamp},v1={signature}

timestamp — Unix timestamp.

signature — HMAC-SHA256 подпись.

Подпись считается от строки:

{timestamp}.{raw_body}

Где raw_body — это исходное тело запроса без изменения форматирования.

Как проверить подпись

Backend продавца должен:

1. Получить raw body запроса.
2. Получить X-Weelay-Timestamp.
3. Получить X-Weelay-Signature.
4. Собрать строку {timestamp}.{raw_body}.
5. Посчитать HMAC-SHA256 с webhook secret проекта.
6. Сравнить полученную подпись с v1 из X-Weelay-Signature.
7. Отклонить webhook, если подпись не совпадает.

Сравнение подписи должно быть безопасным, без обычного сравнения строк, чтобы избежать timing attack.

Проверка времени

Рекомендуется проверять, что X-Weelay-Timestamp не слишком старый.

Например, можно отклонять webhook, если timestamp старше 5 минут.

Это снижает риск повторного использования старого webhook-запроса.

Payload

Webhook body приходит в JSON.

Основные поля payload:

• id — id события;
• event — название события;
• created_at — время создания события;
• data.project — данные проекта;
• data.invoice — данные счёта;
• data.payment — данные оплаты.

Payload может содержать дополнительные поля.

Для бизнес-логики продавцу лучше опираться только на поля, описанные в публичной документации.

invoice.paid

Event invoice.paid означает, что счёт оплачен.

При получении invoice.paid продавец должен:

• проверить подпись webhook;
• найти свой заказ по order_id или invoice id;
• проверить, не был ли заказ уже обработан;
• отметить заказ как оплаченный;
• выдать товар, услугу или доступ;
• сохранить tx_hash, если он нужен для сверки;
• вернуть успешный HTTP-ответ.

Идемпотентная обработка

Webhook может прийти повторно.

Это нормальная ситуация для webhook-доставки.

Backend продавца должен обрабатывать webhook идемпотентно.

Если заказ уже отмечен как оплаченный, повторный webhook не должен повторно выдавать товар, услугу, доступ или создавать вторую запись оплаты.

Что возвращать в ответ

Webhook endpoint должен быстро вернуть успешный HTTP-ответ после корректной обработки.

Рекомендуется возвращать статус 200 или другой успешный 2xx.

Если endpoint возвращает ошибку, Weelay может считать доставку неуспешной.

Не выполняйте долгие операции прямо в webhook handler, если они могут занять много времени.

Безопасность endpoint

Webhook endpoint должен:

• принимать только POST;
• принимать только JSON;
• проверять подпись;
• проверять timestamp;
• не доверять webhook без подписи;
• не выполнять заказ до проверки event;
• не логировать webhook secret;
• не раскрывать внутренние ошибки покупателю.

Что делать при спорной ситуации

Если покупатель утверждает, что оплатил, а webhook не обработался, проверьте:

• invoice id;
• order_id;
• status;
• paid_at;
• tx_hash;
• webhook delivery в dashboard;
• логи своего webhook endpoint.

Если нужен ручной разбор, попросите покупателя предоставить tx_hash.

Тестовый webhook

В dashboard проекта можно использовать тестовую отправку webhook, если она доступна в интерфейсе.

Тестовый webhook нужен, чтобы проверить доступность endpoint, формат обработки и проверку подписи до реальных оплат.

Тестовое событие не должно выдавать товар или услугу покупателю.

Production-чеклист

Перед запуском проверьте:

• webhook URL использует HTTPS;
• endpoint принимает POST;
• endpoint читает raw body;
• подпись X-Weelay-Signature проверяется;
• timestamp проверяется;
• invoice.paid обрабатывается идемпотентно;
• заказ выполняется только один раз;
• webhook secret не попадает в логи;
• ошибки endpoint логируются на стороне продавца.

Итог

Webhook нужен для автоматического уведомления продавца об оплате.

Главный event — invoice.paid.

Главные правила: проверять подпись, обрабатывать событие идемпотентно и выполнять заказ только один раз.