Один обработчик блокирует поток, когда приём события, пять бизнес-действий и HTTP-ответ находятся в одном синхронном `try`. Падение CRM оставляет провайдера без 2xx, он повторяет webhook, а уже отправленное письмо уходит второй раз. Или общий catch возвращает 200, хотя событие нигде не сохранено, — тогда повторения не будет и данные потеряны.

Граница должна проходить раньше: проверить подпись по исходному body, записать неизменённое событие и уникальный provider event id в durable inbox, поставить задания в очередь и только после успешного commit подтвердить приём. Каждый downstream-handler получает собственное состояние, число попыток и идемпотентность. Сбой аналитики больше не откатывает платёжный учёт.

Подтверждать можно только то, что переживёт перезапуск

Состояние запросаHTTP-ответПочему
подпись неверна4xxне принимать недоверенные данные
payload валиден, inbox commit успешен2xxсобытие можно обработать асинхронно
база/очередь недоступна до commit5xxпровайдер должен повторить доставку
event id уже есть2xxдубликат принят идемпотентно
worker позже упалне влияет на старый HTTPошибка живёт в retry конкретного задания

Stripe рекомендует быстро вернуть успешный статус до тяжёлой логики и отдельно предупреждает не менять raw body до проверки подписи. Для другого провайдера сверьте его правила retry и timeout, но принцип durable-before-ack остаётся: 2xx означает, что ответственность за событие уже перешла вашей системе.

Inbox фиксирует факт приёма один раз

CREATE TABLE event_inbox (
  provider       text        NOT NULL,
  event_id       text        NOT NULL,
  event_type     text        NOT NULL,
  received_at    timestamptz NOT NULL,
  payload        jsonb       NOT NULL,
  status         text        NOT NULL DEFAULT 'received',
  PRIMARY KEY (provider, event_id)
);

CREATE TABLE handler_delivery (
  provider       text NOT NULL,
  event_id       text NOT NULL,
  handler        text NOT NULL,
  status         text NOT NULL,
  attempts       integer NOT NULL DEFAULT 0,
  last_error     text,
  PRIMARY KEY (provider, event_id, handler)
);

Payload хранится по политике минимизации: удалите секреты и поля, которые не нужны для повторной обработки, либо зашифруйте их с контролем доступа. Составной ключ защищает от повторной доставки одного события. Уникальность в `handler_delivery` не позволяет дважды создать одинаковое задание для одной пары event/handler.

Fan-out выдаёт каждому handler отдельную судьбу

function receiveWebhook(rawBody, headers) {
  verifySignature(rawBody, headers)
  event = parse(rawBody)

  transaction(() => {
    inserted = inbox.insertIfAbsent(event.provider, event.id, event)
    if (!inserted) return

    for (handler of handlersFor(event.type)) {
      deliveries.insertIfAbsent(event.id, handler.name, 'queued')
      outbox.enqueue(event.id, handler.name)
    }
  })

  return httpResponse(200)
}

Если брокер не участвует в транзакции базы, используйте transactional outbox: commit сохраняет inbox и записи отправки, а отдельный publisher надёжно переносит их в очередь. Прямой вызов `queue.publish()` между SQL insert и commit создаёт окно: сообщение уже ушло, а транзакция откатилась, или наоборот.

Повтор безопасен только с идемпотентным эффектом

Очереди обычно дают at-least-once delivery, поэтому сообщение может прийти повторно даже при настроенном visibility timeout. Идемпотентность строится не на флаге «worker видел event», а на бизнес-ключе эффекта. Для письма это `(event_id, template)`, для проводки — `(provider_object_id, operation_type)`, для CRM — external id с upsert.

  • Сначала резервировать idempotency key в той же транзакции, что и бизнес-изменение.
  • Не отмечать delivery как done до завершения внешнего вызова и сохранения его результата.
  • Различать retryable ошибки сети/5xx и постоянные ошибки валидации.
  • Добавлять jitter к backoff, чтобы восстановившаяся зависимость не получила одновременный шторм.
  • Хранить короткий безопасный error code; токены и полный payload не писать в last_error.

Visibility timeout согласуется с реальным временем работы

В Amazon SQS сообщение после получения временно невидимо. Если worker не удалил его до истечения visibility timeout, другой consumer может получить ту же работу. Слишком короткий timeout создаёт параллельные дубли, слишком длинный задерживает retry после падения. Измерьте p95/p99 длительности каждого handler и оставьте запас; долгую работу продлевайте heartbeat через ChangeMessageVisibility.

СимптомМетрикаКоррекция
два worker делают одноprocessing time > visibilityувеличить/продлевать timeout и проверить idempotency
retry приходит слишком позднонизкая ошибка, высокий timeoutуменьшить базовый timeout
очередь стоит за одним tenantin-flight по partition/groupсменить partitioning без потери порядка
attempt растёт без пользыодинаковый permanent errorостановить retry и отправить в DLQ

DLQ изолирует poison message, но не исправляет его

После ограниченного числа попыток постоянная ошибка переходит в dead-letter queue. Там нужны alarm, причина, версия handler и способ безопасного redrive. AWS отдельно предупреждает, что DLQ может нарушить строгий порядок FIFO-сценария; если порядок бизнес-критичен, сначала решите, можно ли пропустить проблемное событие или требуется остановить только его aggregate.

  1. Открыть одну DLQ-запись и классифицировать ошибку без массового replay.
  2. Исправить код, конфигурацию или данные; развернуть версию и проверить её на копии payload.
  3. Убедиться, что idempotency keys сохранены и уже успешные эффекты не повторятся.
  4. Вернуть малую партию, наблюдая success rate, latency и новые DLQ entries.
  5. Только после контрольной партии выполнить остальной redrive с ограниченной скоростью.

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

Stripe не гарантирует порядок webhook events и советует отслеживать event ID для дублей. Если состояние можно получить из authoritative API, worker загружает актуальный объект и применяет переход по его версии. Если порядок обязателен, сообщения одного aggregate направляются в одну последовательную группу, а версия объекта защищает от старого события, пришедшего позже нового.

Не используйте один глобальный FIFO для всех клиентов: одна poison message снова заблокирует систему. Ключ группировки выбирают по границе порядка — например, `subscription_id` или `order_id`. Независимые заказы остаются параллельными, а события одного заказа проходят последовательно.

Отказоустойчивость доказывается принудительными сбоями

  1. Отправить один event дважды и убедиться, что inbox и каждый эффект созданы один раз.
  2. Выключить CRM: письмо и учёт проходят, CRM delivery повторяется отдельно.
  3. Остановить worker после внешнего вызова, но до ack: повтор не создаёт второй эффект.
  4. Сделать обработку длиннее visibility timeout и проверить heartbeat либо защиту от параллельного дубля.
  5. Дать permanent validation error: сообщение попадает в DLQ после заданного числа попыток.
  6. Вернуть запись из DLQ после исправления и подтвердить trace от исходного event до результата.
  7. Подать события одного объекта в обратном порядке и проверить version/authoritative-read policy.

Для аудита принесите схему HTTP receiver → inbox/outbox → queue → handlers, retry policy каждого consumer, visibility timeout, DLQ redrive policy и trace одного зависшего event. Рабочая система не обязана никогда ошибаться: она обязана локализовать ошибку, не потерять подтверждённое событие, не повторить бизнес-эффект и дать оператору безопасный путь восстановления.

Проверенные источники