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

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

90% команд понимают идемпотентность как «положили idempotency-key в заголовок и забыли». Это детский сад. Ключ сам по себе ничего не гарантирует, если вы не контролируете весь путь запроса: retries, таймауты, гонки между воркерами и повторную доставку событий.

Типовые косяки:
— ключ живёт только в памяти процесса; рестарт — и привет дубли
— ответ не сохраняется, сохраняется лишь статус «успех/ошибка»
— разные параметры запроса с одним и тем же ключом проходят как нормальные
— вебхук обрабатывается дважды, потому что «мы же уже списали»

Правильная схема скучная, как бухгалтерия: ключ должен быть уникален в рамках операции, храниться вместе с хешем входных параметров и финальным ответом, а повторный запрос обязан вернуть тот же результат, а не «почти такой же». Для асинхронщины отдельно фиксируйте состояние по transition-модели: received → processing → succeeded/failed. Идемпотентность или смерть.

Если у вас есть холды, рекурренты и вебхуки, дубли рождаются не в одном месте, а на стыках. Значит, защита нужна везде: на API, на consumer’е очереди и в слое записи в БД. Документация — это ложь, логи — истина.

Итог простой: ключ без persisted state — костыль на костыле и финтехом погоняет. Хотите спать ночью — стройте идемпотентность как часть бизнес-процесса, а не как декоративный заголовок.