Шпаргалка · Взаимодействие
Надёжная отправка вебхуков
Проблема
Платёжный сервис сообщает интернет-магазинам, что платёж прошёл, вызывая их URL: это вебхук. Как отправлять его, не тормозя платежи, как магазину понять, что вызов настоящий и свежий, и как обеим сторонам пережить повторы, дубликаты, события не по порядку и умершие адреса.
Чему вы научитесь
- Почему вебхуки идут через очередь и отправителя, а не внутри платёжного запроса
- HMAC-подпись над id, временем и телом и защита от повторной отправки
- Повторы с растущей паузой и идемпотентный получатель, который отвечает быстро
- Порядок по версии и адреса, которые не отвечают днями
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_payments["API платежей"]
n_shop>"Сервер магазина"]
n_shopdb[("База магазина")]
n_queue[["Очередь вебхуков"]]
n_sender("Отправитель")
n_oldshop>"Мёртвый адрес"]
n_shop -->|"вызов"| n_shopdb
n_payments -->|"асинхронно"| n_queue
n_queue -->|"асинхронно"| n_sender
n_sender -->|"вызов"| n_shop
n_sender --x n_oldshop
classDef down fill:#fde2e2,stroke:#c62828,color:#4a0d0d,stroke-dasharray:4 3
class n_oldshop downMermaid: последовательность запросов
sequenceDiagram
participant n_payments as API платежей
participant n_shop as Сервер магазина
participant n_sender as Отправитель
actor n_attacker as Злоумышленник
participant n_shopdb as База магазина
participant n_oldshop as Мёртвый адрес
Note over n_payments,n_shop: Вебхук отправляется внутри платежа
n_payments->>n_shop: POST /hooks/payments HTTP/1.1
n_shop-->>n_payments: HTTP/1.1 200 OK
Note over n_sender,n_shop: Очередь и отправитель выносят вебхук из платежа
n_sender->>n_shop: sender: deliver evt_9f2 to https://shop.example.com/hooks/payments
n_shop-->>n_sender: HTTP/1.1 200 OK
Note over n_attacker,n_shop: Вызвать URL вебхука магазина может кто угодно
n_attacker->>n_shop: POST /hooks/payments HTTP/1.1
n_shop-->>n_attacker: HTTP/1.1 200 OK
Note over n_sender,n_shop: Каждый вебхук подписывается HMAC
n_sender->>n_shop: POST /hooks/payments HTTP/1.1
Note over n_attacker,n_shop: Настоящий запрос, отправленный снова
n_attacker->>n_shop: POST /hooks/payments (copied from a leaked proxy log)
Note over n_attacker,n_shop: Подписанное время, окно и список увиденных id
n_attacker-xn_shop: shop: verify evt_9f2
Note over n_sender,n_shop: Магазин лежит: повторяем по расписанию
n_sender->>n_shop: POST /hooks/payments HTTP/1.1
n_shop-->>n_sender: HTTP/1.1 503 Service Unavailable
Note over n_sender,n_shop: Медленный ответ превращается в двойной бонус
n_sender->>n_shop: 10:00:00 deliver evt_9f2 attempt 1
Note over n_shop,n_shopdb: Получатель: запомнить id, быстро ответить, работать потом
n_shop->>n_shopdb: INSERT INTO webhook_inbox (webhook_id, received_at)
n_shopdb-->>n_shop: HTTP/1.1 200 OK
Note over n_sender,n_shop: События приходят не по порядку
n_sender->>n_shop: POST /hooks/payments HTTP/1.1
n_shop-->>n_sender: shop: payment pay_771 has version 2, applying 3
Note over n_sender,n_oldshop: Адрес, который уже не вернётся
n_sender->>n_oldshop: endpoint ep_311: failing for 5 daysD2
direction: right
n_payments: "API платежей" {
shape: rectangle
}
n_shop: "Сервер магазина" {
shape: cloud
}
n_shopdb: "База магазина" {
shape: cylinder
}
n_queue: "Очередь вебхуков" {
shape: queue
}
n_sender: "Отправитель" {
shape: rectangle
style.multiple: true
}
n_oldshop: "Мёртвый адрес" {
shape: cloud
style.fill: "#fde2e2"
style.stroke: "#c62828"
style.stroke-dash: 3
}
n_shop -> n_shopdb: "вызов"
n_payments -> n_queue: "асинхронно"
n_queue -> n_sender: "асинхронно"
n_sender -> n_shop: "вызов"
n_sender -> n_oldshop {
target-arrowhead.shape: cross
}PlantUML: последовательность запросов
@startuml
participant "API платежей" as n_payments
boundary "Сервер магазина" as n_shop
participant "Отправитель" as n_sender
actor "Злоумышленник" as n_attacker
database "База магазина" as n_shopdb
boundary "Мёртвый адрес" as n_oldshop
note over n_payments, n_shop : Вебхук отправляется внутри платежа
n_payments -> n_shop : POST /hooks/payments HTTP/1.1
n_shop --> n_payments : HTTP/1.1 200 OK
note over n_sender, n_shop : Очередь и отправитель выносят вебхук из платежа
n_sender -> n_shop : sender: deliver evt_9f2 to https://shop.example.com/hooks/payments
n_shop --> n_sender : HTTP/1.1 200 OK
note over n_attacker, n_shop : Вызвать URL вебхука магазина может кто угодно
n_attacker -> n_shop : POST /hooks/payments HTTP/1.1
n_shop --> n_attacker : HTTP/1.1 200 OK
note over n_sender, n_shop : Каждый вебхук подписывается HMAC
n_sender -> n_shop : POST /hooks/payments HTTP/1.1
note over n_attacker, n_shop : Настоящий запрос, отправленный снова
n_attacker -> n_shop : [дубль] POST /hooks/payments (copied from a leaked proxy log)
note over n_attacker, n_shop : Подписанное время, окно и список увиденных id
n_attacker ->x n_shop : [потеряно] shop: verify evt_9f2
note over n_sender, n_shop : Магазин лежит: повторяем по расписанию
n_sender -> n_shop : [повтор] POST /hooks/payments HTTP/1.1
n_shop --> n_sender : HTTP/1.1 503 Service Unavailable
note over n_sender, n_shop : Медленный ответ превращается в двойной бонус
n_sender -> n_shop : [дубль] 10:00:00 deliver evt_9f2 attempt 1
note over n_shop, n_shopdb : Получатель: запомнить id, быстро ответить, работать потом
n_shop -> n_shopdb : INSERT INTO webhook_inbox (webhook_id, received_at)
n_shopdb --> n_shop : HTTP/1.1 200 OK
note over n_sender, n_shop : События приходят не по порядку
n_sender -> n_shop : POST /hooks/payments HTTP/1.1
n_shop --> n_sender : shop: payment pay_771 has version 2, applying 3
note over n_sender, n_oldshop : Адрес, который уже не вернётся
n_sender -> n_oldshop : endpoint ep_311: failing for 5 days
@endumlPlantUML: компоненты
@startuml
left to right direction
component "API платежей" as n_payments
cloud "Сервер магазина" as n_shop
database "База магазина" as n_shopdb
queue "Очередь вебхуков" as n_queue
collections "Отправитель" as n_sender
cloud "Мёртвый адрес" as n_oldshop #fde2e2;line:c62828;line.dashed
n_shop --> n_shopdb : вызов
n_payments --> n_queue : асинхронно
n_queue --> n_sender : асинхронно
n_sender --> n_shop : вызов
n_sender -[#c62828]-> n_oldshop
@endumlИтог
Шесть правил вебхуков.
1) Отправляйте из очереди с таймаутом, никогда внутри бизнес-запроса. 2) Подписывайте id, время и сырое тело секретом отдельного адреса; проверяйте за постоянное время. 3) Отклоняйте старое время и помните увиденные id. 4) Повторяйте по растущему расписанию со случайным разбросом. 5) Получатель сохраняет id с уникальным ключом, быстро отвечает и работает в фоне. 6) Не полагайтесь на порядок: используйте версии или забирайте текущее состояние; изолируйте и отключайте мёртвые адреса.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Платёж p95 | 8 200 мс | 60 мс |
| Принято поддельных | 0 | 0 |
| Двойные выполнения | 0/день | 0/день |
| Ждут доставки | 0 | 9 000 |
Шаги
- Кейс Вебхук отправляется внутри платежа
Когда оплата картой прошла, API платежей вызывает URL магазина с новостью и ждёт ответа, прежде чем ответить покупателю.
- Решение Очередь и отправитель выносят вебхук из платежа
API платежей теперь сохраняет событие и сразу отвечает покупателю.
- Проблема Вызвать URL вебхука магазина может кто угодно
URL не секрет: он виден в инструментах браузера, логах и тикетах поддержки.
- Решение Каждый вебхук подписывается HMAC
Каждый магазин получает свой секрет при регистрации адреса.
- Проблема Настоящий запрос, отправленный снова
Неправильно настроенный прокси логировал запросы целиком, и лог утёк.
- Решение Подписанное время, окно и список увиденных id
Подписывается строка
id.timestamp.body, поэтому время нельзя поменять, не сломав подпись. - Решение Магазин лежит: повторяем по расписанию
Сервер магазина лежит час во время деплоя.
- Проблема Медленный ответ превращается в двойной бонус
Магазин обрабатывает событие прямо в запросе: отмечает заказ оплаченным и начисляет 500 бонусов.
- Решение Получатель: запомнить id, быстро ответить, работать потом
Магазин сначала вставляет
Webhook-Idв таблицу inbox с уникальным ключом. - Кейс События приходят не по порядку
Платёж прошёл, а через пять минут его вернули.
- Решение Адрес, который уже не вернётся
Один магазин закрылся, и его домен истёк.
- Итоги Итог
Шесть правил вебхуков.
Термины
- Вебхук (webhook)
- Когда происходит событие, одна система сама шлёт HTTP POST на URL другой. Доставка как минимум один раз: отправитель повторяет с backoff, а получатель отбрасывает дубли по id события.
- HMAC-подпись
- Тело сообщения и метка времени хешируются общим секретом, результат идёт в заголовке. Получатель считает так же и сравнивает: не совпало или метка старая — запрос отклоняется.