Webhooks — Обзор

Webhook’и — авторитетный сигнал. Браузерные callback’и (onSuccess) и представления панели — удобство; webhook’и — истина.

Гарантии доставки

• Не менее одного раза. Одно событие может быть доставлено до 6 раз, если ваш сервер не возвращает 2xx в течение таймаута. Делайте обработчик идемпотентным — дедуплицируйте по X-Delivery (payload не имеет поля event_id; стабильный delivery UUID — это ключ идемпотентности).
• Одно событие на HTTP-запрос. Без батчинга.
• Изоляция per-endpoint. Если у вас несколько зарегистрированных endpoint’ов, у каждого свой трек доставки + повторов. Один медленный URL мерчанта не может голодать другие — у каждого хоста собственный circuit breaker.
• Подписано. Каждый payload несёт заголовок X-Signature (а в течение 24-часового окна после ротации — также X-Signature-Prev). Проверяйте до того, как что-либо делать с телом. См. Проверка подписи.

Подписываемые типы событий

Панель получает этот список из GET /v1/webhooks/event-types, чтобы форма создания / редактирования endpoint’а всегда соответствовала тому, что платформа реально отправляет. Подписка на событие, которое мы не отправляем, будет отклонена на этапе создания с чёткой ошибкой.

Payload + заголовки

HTTP-тело — это напрямую объект данных конкретного события. Нет внешнего Stripe-стиля конверта — поля вроде типа события, delivery ID и timestamp эмиссии живут в заголовках. Для payment.settled тело выглядит так:

{
  "receipt_id":        "rcp_…",
  "order_id":          "ord_…",
  "payment_intent_id": "pin_…",
  "checkout_session_id": "cst_…",
  "merchant_id":       "mer_…",
  "customer_id":       "cus_…",
  "total":             "49.00",
  "currency":          "USD",
  "payment_method":    "crypto",
  "token":             "USDC",
  "network":           "polygon",
  "tx_hash":           "0x…",
  "deposit_address":   "0x…",
  "treasury_address":  "0x…",
  "amount_received":   "49.00",
  "confirmations":     5,
  "metadata":          { /* per-event */ }
}

Другие события несут свой набор полей — см. publisher-структуры в payment-service/internal/domain/events.go для канонической формы, пока per-event документация не появится. Имена полей стабильны (нижний snake_case); on-chain tx hash всегда tx_hash (не transaction_hash).

Заголовки входящего запроса

Content-Type:      application/json
X-Event:           payment.settled
X-Delivery:        7c9e6679-7425-40de-944b-e07fc1f90ae7
Idempotency-Key:   7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Timestamp:       1729536000
X-Signature:       sha256=9a8b7c…
X-Signature-Prev:  sha256=fa31b2…    (только в течение grace-окна ротации)

Расписание повторов

Если ваш endpoint не возвращает 2xx в течение таймаута, мы повторяем по этому расписанию (timestamp’ы относительно первой попытки):

После того как попытка 6 не удалась, доставка переводится в dead letter, и email мерчантского аккаунта уведомляется. Dead-lettered события можно проиграть заново из панели Developers → Webhooks → Delivery history или напрямую через POST /v1/webhooks/deliveries/:id/replay. Каждый replay создаёт новую строку доставки со своим X-Delivery — аудиторская цепочка возвращается к оригиналу через parent_delivery_id, чтобы повторы replay’ев не затеняли исходное событие.

Регистрация endpoint’а

Из панели мерчанта :

1. Developers → Webhooks → + Add endpoint
2. Вставьте ваш URL — только https://… (обычный HTTP отклоняется; форма создания также блокирует localhost, частные IP-диапазоны и URL с userinfo)
3. Выберите события для подписки (или * для всех)
4. Выберите окружение — test или live (у каждого свой секрет; они никогда не пересекаются)
5. Save → панель отображает секрет подписи (whsec_…) один раз. Сохраните его на сервере; он понадобится для следующих двух фич.

Вы можете зарегистрировать до 10 endpoint’ов на окружение на мерчанта (например, один для обработки в продакшене, один для зеркалирования в staging, один для уведомлений в Slack). У каждого своё состояние повторов, секрет и per-host circuit breaker.

Действия жизненного цикла на каждом endpoint’е

Меню ⋮ на карточке каждого endpoint’а показывает:

• Edit — изменить URL, описание или список подписок. Новый URL пере-валидируется теми же правилами https:///SSRF, что и при создании.
• Send Test — синхронный POST конверта webhook.test.ping, подписанный вашим текущим секретом. Панель показывает HTTP-статус, latency и 512-байтный сниппет вашего ответа. Минует RMQ-pipeline, чтобы ответ был мгновенным.
• Rotate Secret — генерирует новый секрет. Предыдущий остаётся валидным 24 часа (доставки несут и X-Signature, и X-Signature-Prev в окне, чтобы verifier’ы, работающие с любым из ключей, продолжали принимать события, пока вы переразворачиваете).
• Reveal Secret — повторно отображает существующий секрет. Защищён свежей 2FA-проверкой и записывается в журнал аудита; используйте, только когда вы потеряли копию и Rotate неприемлем.
• Enable / Disable — переключает is_active без потери истории доставки. Отключённые endpoint’ы остаются в панели, но не получают новых доставок.
• Delete — необратимо. Используйте Disable, если можете переключиться обратно позже.

Советы для обработчиков

1. Возвращайте 2xx быстро. Подтверждайте 200 OK до тяжёлой работы — кидайте обработку в фоновую очередь. Таймаут per-попытка — 10 секунд; удержание ответа дольше этого триггерит повтор. Таймаут на стороне платформы и не настраивается мерчантом — пишите в поддержку, если ваш обработчик действительно нуждается в большем времени.
2. Дедуплицируйте по X-Delivery (или Idempotency-Key — то же значение). Даже если вы возвращаете 2xx, upstream-прокси может уронить соединение и спровоцировать повтор; delivery ID стабилен между каждым повтором одной строки доставки, поэтому это правильный ключ.
3. Толерируйте неизвестные типы событий. Новые события могут появиться; возвращайте 200 и no-op, а не 4xx, иначе заполните очередь повторов.
4. Логируйте X-Delivery рядом с бизнес-логикой. Когда что-то пошло не так, это ключ join между нашей стороной и вашей.

Что дальше

• Проверка подписи — точный алгоритм + паттерны защиты от replay.
• Концепции → Сессии — в каком состоянии сессия, когда срабатывает каждое событие.