Table of contents
- Что такое вебхуки и зачем они нужны
- Настройка endpoint и проверка подписи
- Типы событий и полезные payload поля
- Ретраи, порядок доставки и идемпотентность
- Стратегии обработки: очереди, дедупликация, повтор
- Защита вебхуков: сеть, WAF, аудит
- Отладка и повторная отправка событий
- Типичные ошибки и чек‑лист надежности
Что такое вебхуки и зачем они нужны
Вебхуки — это HTTP‑уведомления от провайдера в ваш backend, которые сигнализируют об изменении состояния ресурса: платеж совершился, возврат завершен, вывод средств выполнен. Они позволяют синхронизировать вашу базу с реальным результатом, избегая постоянного polling и ускоряя бизнес‑процессы (выдача доступа, печать чека, обновление статуса заказа).
Настройка endpoint и проверка подписи
Укажите публичный URL, принимающий POST JSON, например https://shop.example.ru/webhooks/payments. Каждый запрос содержит заголовки X-Event-Type, X-Request-Id и X-Signature (HMAC SHA‑256). Для валидации:
- Прочитайте сырое тело запроса без трансформаций.
- Вычислите HMAC по секрету endpoint.
- Сравните с X-Signature в постоянном времени.
Ответ 200–204 подтверждает прием. Допускается ответ 202 с асинхронной обработкой через очередь.
Типы событий и полезные payload поля
Основные события:
- payment.succeeded / payment.failed / payment.canceled
- payment.waiting_for_capture (для двухэтапной оплаты)
- refund.succeeded / refund.failed
- payout.succeeded / payout.failed
В payload ищите: data.object.id, status, amount, order_id, receipt_info, created_at, version. В metadata можно передавать идентификаторы из вашей системы.
Ретраи, порядок доставки и идемпотентность
Доставка событий «at least once»: возможны дубликаты и перестановки. Мы повторяем отправку по экспоненте до 24 часов или пока не получим 2xx. Рекомендуется:
- Писать события в очередь (Kafka/RabbitMQ/SQS) и обрабатывать идемпотентно по event.id.
- Хранить последнюю version ресурса и игнорировать более старые.
- Реализовать дедупликацию по X-Request-Id или event.id.
Стратегии обработки: очереди, дедупликация, повтор
Схема: HTTP endpoint → очередь → worker. Worker проверяет подпись, делает проверку дубликатов, транзакционно обновляет БД и создает side‑effects (например, отправка письма). Для надежности используйте outbox‑pattern и транзакционные сообщения.
Защита вебхуков: сеть, WAF, аудит
- Принимайте только HTTPS, настройте TLS 1.2+.
- Ограничьте доступ по IP‑диапазонам провайдера или через подпись запроса.
- Используйте WAF/Rate Limit, чтобы избежать DDoS/Bruteforce.
- Логируйте X-Request-Id и event.id для трассировки.
Отладка и повторная отправка событий
В панели можно просматривать историю событий, payload, подписи и инициировать повторную отправку. В песочнице доступны симуляции сценариев: success, decline, chargeback, refund.
Типичные ошибки и чек‑лист надежности
- Не подтвержден прием (не 2xx): провайдер будет бесконечно ретраить → настроьте ответ 200/204.
- Потеря тела при парсинге: сохраняйте raw body для подписи.
- Дублирование эффектов: используйте идемпотентность и транзакции.
- Чек‑лист: подпись, очередь, дедупликация, мониторинг, алерты, ретраи, replay‑защита.