Один хук — много сервисов: как не утопить интеграции в хаосе fan-out

Один хук — много сервисов: как не утопить интеграции в хаосе fan-out

Fan-out выглядит просто: пришёл один webhook, дальше разослали событие в CRM, биллинг, аналитику и нотификации. На практике это место, где умирают SLA: один получатель тормозит, другой отдаёт 500, третий принимает мусор и молча ломает пайплайн.

Базовая схема такая: ingress-хендлер только валидирует подпись, режет дубликаты по event_id и кладёт полезную нагрузку в очередь. Дальше отдельный dispatcher читает событие и публикует в набор downstream-очередей или вызывает сервисы асинхронно. Не делайте fan-out синхронным в HTTP-обработчике — это прямой путь к таймаутам и каскадным ретраям.

Для каждого получателя нужен свой контракт. Один и тот же payload редко подходит всем: где-то нужен нормализованный JSON, где-то — только часть метаданных. Прокидываем стейт через метаданные, добавляем correlation_id и версию схемы. Если сервис не принимает событие, он должен вернуть отказ, а не «успешно проглотить и забыть».

{
"event_id": "evt_123",
"type": "order.paid",
"correlation_id": "c-8891",
"targets": ["crm", "billing", "slack"]
}

Идемпотентность — это не роскошь, а база. Храните delivery ledger: кто получил, кто в ретрае, кто dead-lettered. Ретрай-политика решает всё: короткие повторные попытки для 5xx, отдельный путь для 4xx, лимит попыток и алерт на деградацию. Иначе вы не распределяете нагрузку, а размножаете инцидент.

Если нужен fan-out, начинайте не с кода, а с таблицы отказов. Где хранится состояние, как гасим дубликаты, кто отвечает за DLQ, и что будет, если один получатель лежит сутки. Смотрим в тело запроса и проектируем так, будто внешний API уже упал.