Что такое вебхук (webhook) в платёжной системе
Вебхук (webhook) — HTTP-запрос, который сервис отправляет на ваш сервер, когда происходит событие, например платёж оплачен или выплата отправлена.
Без вебхуков магазину пришлось бы постоянно спрашивать платёжный сервис: «оплачен ли заказ?». Это медленно и создаёт лишнюю нагрузку. Вебхук работает наоборот: вы один раз указываете URL своего обработчика, и при каждом событии сервис сам отправляет туда POST-запрос с данными — идентификатором платежа, статусом, суммой.
Главное правило: вебхук — единственный надёжный сигнал оплаты. Возврат клиента со страницы оплаты на сайт ничего не доказывает — он мог просто закрыть вкладку или подделать ссылку. Товар или доступ выдаются по вебхуку (или после проверки статуса через API), а не по редиректу.
Вебхук нужно уметь проверять. URL обработчика публичен, и кто угодно может отправить на него запрос с выдуманным «оплачено». Поэтому сервисы подписывают тело запроса секретным ключом — обычно HMAC — и передают подпись в заголовке. Обработчик пересчитывает подпись и сравнивает её с полученной; если не совпало, запрос отклоняется.
Второе правило — идемпотентная обработка. Сервис повторяет доставку, если ваш сервер не ответил успешным кодом, был недоступен или ответил слишком медленно. Значит, одно и то же событие может прийти несколько раз. Обработчик должен запоминать уже обработанные события и не выдавать товар повторно. Хорошая практика — быстро ответить 2xx, а тяжёлую работу выполнять в фоне.
Moonvex подписывает вебхуки HMAC (заголовок Moonvex-Signature), повторяет доставку до трёх дней и показывает журнал доставок в кабинете — по нему видно, что ушло и что ответил ваш сервер.
Чек-лист обработчика вебхуков
- Проверяйте подпись по сырому телу запроса.
- Отвечайте 2xx быстро, тяжёлую работу — в очередь.
- Храните обработанные события и игнорируйте повторы.
- Не доверяйте редиректу со страницы оплаты.
- Логируйте входящие запросы для разбора инцидентов.