Идемпотентность спасает, когда вебхук приходит дважды и платёж уже списан

Идемпотентность спасает, когда вебхук приходит дважды и платёж уже списан

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

Базовый паттерн: у каждого события должен быть стабильный idempotency key. Это может быть внешний event_id, хеш полезной нагрузки или составной ключ из source + object_id + action. Ключ пишется в хранилище вместе со статусом обработки: received, processing, done, failed. Без этого “один раз” — просто надежда.


INSERT INTO webhook_events(key, status, payload)
VALUES ($1, 'received', $2)
ON CONFLICT (key) DO NOTHING;


Если insert не прошёл — это дубль, сразу 200 OK без повторной бизнес-логики. Если прошёл — кладём задачу в очередь, а воркер уже делает side effects. Идемпотентность — это не роскошь, а база: запись в БД, отправка письма, списание баллов должны быть защищены тем же ключом или транзакционной проверкой.

Отдельно проверяйте ретраи от внешнего API: некоторые системы шлют один и тот же payload с разными заголовками, но одинаковым смыслом. Смотрим в тело запроса, валидируем схему, не доверяем порядку доставки, и никогда не завязываем дедупликацию только на timestamp.

Итог простой: сначала дедупликация на входе, потом очередь, потом side effects. Если пропустить первый шаг, ловим 5xx на ровном месте и чинить уже нечего — только пересчитывать последствия.