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

Что такое вебхуки и зачем они нужны

Вебхуки — это HTTP‑уведомления от провайдера в ваш backend, которые сигнализируют об изменении состояния ресурса: платеж совершился, возврат завершен, вывод средств выполнен. Они позволяют синхронизировать вашу базу с реальным результатом, избегая постоянного polling и ускоряя бизнес‑процессы (выдача доступа, печать чека, обновление статуса заказа).

Настройка endpoint и проверка подписи

Укажите публичный URL, принимающий POST JSON, например https://shop.example.ru/webhooks/payments. Каждый запрос содержит заголовки X-Event-Type, X-Request-Id и X-Signature (HMAC SHA‑256). Для валидации:

1. Прочитайте сырое тело запроса без трансформаций.
2. Вычислите HMAC по секрету endpoint.
3. Сравните с 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‑защита.