Один обработчик блокирует поток, когда приём события, пять бизнес-действий и HTTP-ответ находятся в одном синхронном `try`. Падение CRM оставляет провайдера без 2xx, он повторяет webhook, а уже отправленное письмо уходит второй раз. Или общий catch возвращает 200, хотя событие нигде не сохранено, — тогда повторения не будет и данные потеряны.
Граница должна проходить раньше: проверить подпись по исходному body, записать неизменённое событие и уникальный provider event id в durable inbox, поставить задания в очередь и только после успешного commit подтвердить приём. Каждый downstream-handler получает собственное состояние, число попыток и идемпотентность. Сбой аналитики больше не откатывает платёжный учёт.
Подтверждать можно только то, что переживёт перезапуск
| Состояние запроса | HTTP-ответ | Почему |
|---|---|---|
| подпись неверна | 4xx | не принимать недоверенные данные |
| payload валиден, inbox commit успешен | 2xx | событие можно обработать асинхронно |
| база/очередь недоступна до commit | 5xx | провайдер должен повторить доставку |
| 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 |
| очередь стоит за одним tenant | in-flight по partition/group | сменить partitioning без потери порядка |
| attempt растёт без пользы | одинаковый permanent error | остановить retry и отправить в DLQ |
DLQ изолирует poison message, но не исправляет его
После ограниченного числа попыток постоянная ошибка переходит в dead-letter queue. Там нужны alarm, причина, версия handler и способ безопасного redrive. AWS отдельно предупреждает, что DLQ может нарушить строгий порядок FIFO-сценария; если порядок бизнес-критичен, сначала решите, можно ли пропустить проблемное событие или требуется остановить только его aggregate.
- Открыть одну DLQ-запись и классифицировать ошибку без массового replay.
- Исправить код, конфигурацию или данные; развернуть версию и проверить её на копии payload.
- Убедиться, что idempotency keys сохранены и уже успешные эффекты не повторятся.
- Вернуть малую партию, наблюдая success rate, latency и новые DLQ entries.
- Только после контрольной партии выполнить остальной redrive с ограниченной скоростью.
Порядок событий нельзя угадывать по времени доставки
Stripe не гарантирует порядок webhook events и советует отслеживать event ID для дублей. Если состояние можно получить из authoritative API, worker загружает актуальный объект и применяет переход по его версии. Если порядок обязателен, сообщения одного aggregate направляются в одну последовательную группу, а версия объекта защищает от старого события, пришедшего позже нового.
Не используйте один глобальный FIFO для всех клиентов: одна poison message снова заблокирует систему. Ключ группировки выбирают по границе порядка — например, `subscription_id` или `order_id`. Независимые заказы остаются параллельными, а события одного заказа проходят последовательно.
Отказоустойчивость доказывается принудительными сбоями
- Отправить один event дважды и убедиться, что inbox и каждый эффект созданы один раз.
- Выключить CRM: письмо и учёт проходят, CRM delivery повторяется отдельно.
- Остановить worker после внешнего вызова, но до ack: повтор не создаёт второй эффект.
- Сделать обработку длиннее visibility timeout и проверить heartbeat либо защиту от параллельного дубля.
- Дать permanent validation error: сообщение попадает в DLQ после заданного числа попыток.
- Вернуть запись из DLQ после исправления и подтвердить trace от исходного event до результата.
- Подать события одного объекта в обратном порядке и проверить version/authoritative-read policy.
Для аудита принесите схему HTTP receiver → inbox/outbox → queue → handlers, retry policy каждого consumer, visibility timeout, DLQ redrive policy и trace одного зависшего event. Рабочая система не обязана никогда ошибаться: она обязана локализовать ошибку, не потерять подтверждённое событие, не повторить бизнес-эффект и дать оператору безопасный путь восстановления.