← Назад в блог
Integrations2026-07-09

Webhook архитектура: retries, idempotency и защита от дублей

Как строить надежные webhook-интеграции: повторы, дедупликация, подписи и мониторинг доставки.

Интеграции и webhook события

Почему webhook ломается

События приходят повторно, в неправильном порядке и иногда с задержкой. Это нормальное поведение сети.

Что обязательно

  • event_id в каждом событии
  • подпись webhook (HMAC)
  • idempotency key в обработчике
  • DLQ для неуспешных событий

Retry стратегия

  • exponential backoff
  • лимит попыток
  • алерт после попадания в DLQ

Проверка

  • Тест повторной доставки одного и того же события
  • Тест reorder событий
  • Тест истекшей подписи

Архитектурный шаблон обработчика

Надёжный webhook flow обычно выглядит так:

  1. Принять запрос и проверить подпись.
  2. Проверить event_id на дубликат в storage.
  3. Сохранить событие в inbox/outbox таблицу.
  4. Вернуть 2xx как можно быстрее.
  5. Асинхронно обработать бизнес-логику через worker.

Так вы избегаете таймаутов на стороне отправителя и не теряете события.

Idempotency: практический пример

CREATE TABLE processed_events (
  event_id TEXT PRIMARY KEY,
  received_at TIMESTAMP NOT NULL DEFAULT NOW()
);

Алгоритм:

  • если event_id нет -> вставить и обработать;
  • если уже есть -> вернуть success и не выполнять повторно бизнес-действие.

Это защищает от дублей даже при сетевых повторах.

Порядок событий (ordering)

Некоторые провайдеры не гарантируют порядок доставки.
Поэтому обработчик должен быть устойчив к сценарию, когда updated пришёл раньше created.

Подход:

  • хранить версию сущности (version/updated_at);
  • применять только более новую версию;
  • поздние/устаревшие события игнорировать или отправлять в reconciliation.

Безопасность webhook

  • HMAC подпись в заголовке;
  • ограничение по времени (timestamp tolerance);
  • IP allowlist (если доступен у провайдера);
  • rate limiting по endpoint.

Если подпись не проверяется строго, webhook endpoint становится уязвимым для spoofing.

Retry и DLQ стратегия

Рекомендуемые правила:

  • Retry: 5-8 попыток, exponential backoff.
  • На 5xx — retry, на 4xx обычно stop (если ошибка не transient).
  • После лимита — DLQ + alert ответственному.

DLQ без процесса разбора бесполезна. Нужен owner и SLA "разобрать событие из DLQ за N часов".

Мониторинг качества интеграции

Смотрите минимум:

  • delivery success rate;
  • duplicate rate;
  • average processing latency;
  • DLQ volume по провайдерам.

Эти метрики хорошо показывают деградацию до того, как её заметит бизнес.

Чеклист production

  • Верификация подписи реализована
  • Idempotency на уровне storage
  • Асинхронная обработка через очередь/worker
  • DLQ + алерты + owner
  • Есть runbook восстановления событий

Вывод

Webhook-интеграция становится надёжной не из-за "идеальной сети", а благодаря инженерной дисциплине: idempotency, retries, мониторинг и операционный процесс для ошибок.