Сквозная идемпотентность вебхуков: где биллинг теряет деньги на дублях

Сквозная идемпотентность вебхуков: где биллинг теряет деньги на дублях

Платежный провайдер может прислать один и тот же вебхук несколько раз, в другом порядке или после таймаута на вашей стороне. Если обработчик не защищен, вы получите двойное зачисление, повторный перевод статуса или «зависший» заказ без финальной фиксации. Идемпотентность в биллинге — это не рекомендация, а базовый вопрос выживания системы.

Слой защиты должен быть сквозным:
• входящий event_id или transaction_id — в уникальный ключ;
• запись о событии — до бизнес-эффекта, в одной транзакции;
• проверка дубля — на уровне БД, а не только в памяти процесса;
• обработчик — повторяемый без побочных эффектов при ретраях и ребалансировках очереди.

Отдельная ошибка — считать, что достаточно дедупликации по внешнему ID. Один и тот же платеж часто порождает цепочку событий: authorized, captured, settled, reversed. Для каждого типа нужна своя модель состояния и своя матрица переходов. Иначе вы либо «съедите» легитимное событие, либо начислите деньги дважды.

Практика простая: храните журнал входящих вебхуков, сводите его с внутренним ledger, а бизнес-команду переводите только через транзакционную запись с уникальным ограничением. Если событие уже обработано, ответ должен быть успешным и пустым — без повторной логики. Так и строится системная защита от revenue leakage.