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

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

Платежный провайдер почти всегда будет присылать один и тот же вебхук несколько раз: из-за ретраев, таймаута, сетевого сплита или рассинхрона между шиной и БД. Если обработчик не защищён, вы получите двойную активацию подписки, повторный refund или повторное начисление кредита.

Базовый паттерн такой: у каждого события должен быть стабильный внешний идентификатор, а в БД — уникальный ключ на этот id. Сначала пишем запись о получении события в таблицу inbox, затем в одной транзакции проверяем, не обработан ли оно уже, и только после этого меняем бизнес-состояние. Идемпотентность в биллинге — это не рекомендация, а базовый вопрос выживания системы.

Нельзя строить защиту только на status=paid. У провайдера может прийти payment_succeeded повторно, а у вас уже создана подписка. Нельзя полагаться и на «последнюю версию» объекта: вебхук может приехать позже, чем асинхронный polling, и без версии события вы откатите корректное состояние. Для спорных кейсов храните event_type, provider_event_id, entity_id и хэш полезной нагрузки.

Отдельно проектируйте повторы: если запись в БД прошла, а ответ провайдеру не ушёл, он повторит доставку. Обработчик должен быть безопасен при re-delivery и при частичном падении после commit. На практике это означает: атомарная запись, уникальные ограничения, outbox для побочных эффектов и строгий порядок переходов состояния. Давайте разберем, что происходит с транзакцией в момент сетевого сплита шлюза.

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