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

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

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

База простая: у каждого события должен быть стабильный ключ. Это может быть event_id, delivery_id, order_id + тип операции. Ключ кладём в уникальный индекс и сначала пытаемся зафиксировать факт обработки, а уже потом запускаем бизнес-логику. Если вставка не прошла по конфликту — значит, этот запрос уже видели. Идемпотентность — это не роскошь, а база.

INSERT INTO webhook_events(event_key, payload_hash, status)
VALUES (:key, :hash, 'new')
ON CONFLICT (event_key) DO NOTHING;

Не доверяйте телу запроса слепо. Смотрим в тело запроса, но только после проверки подписи, схемы и обязательных полей. Для тяжёлых операций лучше ставить очередь: вебхук отвечает 200 после записи в outbox, а воркер уже делает побочные эффекты. Тогда ретраи не ломают внешний API, а повторный запрос лишь перезаписывает тот же state.

Финал: дубли убираются не магией, а дисциплиной — уникальный ключ, атомарная запись, проверка подписи, очередь и retry-safe обработчики. Ретрай-политика решает всё, если вы заранее сделали её безболезненной.