mufassall

Шпаргалка · Взаимодействие

Надёжная отправка вебхуков

14 мин · Средний · mufassall.dtwin.uz/ru/l/webhooks/

← Открыть урок

Проблема

Платёжный сервис сообщает интернет-магазинам, что платёж прошёл, вызывая их URL: это вебхук. Как отправлять его, не тормозя платежи, как магазину понять, что вызов настоящий и свежий, и как обеим сторонам пережить повторы, дубликаты, события не по порядку и умершие адреса.

Чему вы научитесь

  • Почему вебхуки идут через очередь и отправителя, а не внутри платёжного запроса
  • HMAC-подпись над id, временем и телом и защита от повторной отправки
  • Повторы с растущей паузой и идемпотентный получатель, который отвечает быстро
  • Порядок по версии и адреса, которые не отвечают днями
Итоговая сцена
15%25%70%

Диаграмма как код

Итоговая схема урока в виде текста: вставьте её в 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 down

Mermaid: последовательность запросов

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 days

D2

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
@enduml

PlantUML: компоненты

@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) Не полагайтесь на порядок: используйте версии или забирайте текущее состояние; изолируйте и отключайте мёртвые адреса.

Показатели: в начале и в конце

ПоказательВ началеВ конце
Платёж p958 200 мс60 мс
Принято поддельных00
Двойные выполнения0/день0/день
Ждут доставки09 000

Шаги

  1. Кейс Вебхук отправляется внутри платежа

    Когда оплата картой прошла, API платежей вызывает URL магазина с новостью и ждёт ответа, прежде чем ответить покупателю.

  2. Решение Очередь и отправитель выносят вебхук из платежа

    API платежей теперь сохраняет событие и сразу отвечает покупателю.

  3. Проблема Вызвать URL вебхука магазина может кто угодно

    URL не секрет: он виден в инструментах браузера, логах и тикетах поддержки.

  4. Решение Каждый вебхук подписывается HMAC

    Каждый магазин получает свой секрет при регистрации адреса.

  5. Проблема Настоящий запрос, отправленный снова

    Неправильно настроенный прокси логировал запросы целиком, и лог утёк.

  6. Решение Подписанное время, окно и список увиденных id

    Подписывается строка id.timestamp.body, поэтому время нельзя поменять, не сломав подпись.

  7. Решение Магазин лежит: повторяем по расписанию

    Сервер магазина лежит час во время деплоя.

  8. Проблема Медленный ответ превращается в двойной бонус

    Магазин обрабатывает событие прямо в запросе: отмечает заказ оплаченным и начисляет 500 бонусов.

  9. Решение Получатель: запомнить id, быстро ответить, работать потом

    Магазин сначала вставляет Webhook-Id в таблицу inbox с уникальным ключом.

  10. Кейс События приходят не по порядку

    Платёж прошёл, а через пять минут его вернули.

  11. Решение Адрес, который уже не вернётся

    Один магазин закрылся, и его домен истёк.

  12. Итоги Итог

    Шесть правил вебхуков.

Термины

Вебхук (webhook)
Когда происходит событие, одна система сама шлёт HTTP POST на URL другой. Доставка как минимум один раз: отправитель повторяет с backoff, а получатель отбрасывает дубли по id события.
HMAC-подпись
Тело сообщения и метка времени хешируются общим секретом, результат идёт в заголовке. Получатель считает так же и сравнивает: не совпало или метка старая — запрос отклоняется.