Если обработчик делает только `subscription.valid_until = new_date`, он неизбежно стирает рассказ о том, как срок менялся. Откройте одну подписку и сравните число invoice у провайдера с числом локальных операций. Разница сразу показывает, потеряна ли история или интерфейс просто её не выводит.

Не восстанавливайте прошлое из текущего `valid_until` арифметикой. Паузы, бесплатные периоды, смены плана, ручные invoice и неуспешные попытки делают такую реконструкцию недостоверной. Источником backfill служат реальные provider objects и ваши неизменяемые журналы.

Три сущности отвечают на три вопроса

СущностьВопросМожно обновлять
subscription snapshotдоступ активен сейчас?да
invoice/paymentчто выставлено и оплачено?только синхронизировать статус
renewal ledgerкакое изменение уже произошло?нет, только коррекция новой записью
webhook inboxчто доставил провайдер?статус обработки

Ledger не обязан быть бухгалтерской книгой в юридическом смысле. Это технический журнал доменных фактов: период продлён, оплата не прошла, доступ изменён вручную. Финансовый учёт и признание выручки проектируются отдельно со специалистами.

Строка продления имеет внешний якорь

renewal_ledger:
  id, subscription_id
  provider, provider_invoice_id UNIQUE
  period_start, period_end
  amount_minor, currency, outcome
  occurred_at, recorded_at
  source_event_id, metadata_version

webhook_inbox:
  provider_event_id UNIQUE, event_type, received_at, processed_at, payload_ref

Уникальность по invoice ID удобна для одного провайдера; для нескольких добавьте provider. Если один invoice содержит несколько значимых строк или изменений, определите более точный доменный ключ. Суммы храните вместе с валютой и не выводите период только из даты платежа.

Доставка webhook не является последовательным логом

Stripe прямо предупреждает, что порядок событий не гарантирован, один event может быть доставлен повторно, а пропущенный объект можно получить через API. Поэтому `invoice.paid` может оказаться у вас раньше соседнего subscription event. Обработчик не должен требовать предыдущего события в памяти: сохраните inbox, загрузите недостающие invoice/subscription и примените идемпотентную команду.

  • Проверить подпись webhook по raw body до изменения данных.
  • Зафиксировать provider event ID уникально до бизнес-обработки.
  • Быстро вернуть успешный HTTP-ответ, а тяжёлую работу отправить в очередь.
  • Повтор уже обработанного event завершать без второй ledger-строки.
  • Не определять порядок только по timestamp: разные события могут совпасть по секунде.

Paid invoice и активная подписка проверяются вместе

По документации Stripe `invoice.paid` означает успешную оплату invoice, но перед продлением доступа рекомендуется получить связанную subscription и проверить её состояние. В вашей системе определите, какой факт создаёт ledger row и какой меняет entitlement. Это может быть одна транзакция, но две явные операции: записать историю и обновить текущую проекцию доступа.

Event/объектИсторияТекущая проекция
invoice.paidуспешная операцияпродлить по подтверждённому периоду
invoice.payment_failedнеуспешная попыткане добавлять оплаченный срок
subscription updatedсмена плана/статусаобновить snapshot
manual grantотдельный доменный фактизменить доступ с actor/reason
duplicate eventничего новогоничего нового

Backfill работает пакетами и с provenance

  1. Сделать резервную копию и выгрузить список затронутых subscription IDs.
  2. Постранично получить invoice из API провайдера за выбранный период.
  3. Сопоставить provider customer/subscription с локальной записью.
  4. Создать отсутствующие ledger rows через ту же idempotent-команду.
  5. Пометить источник как backfill и сохранить дату синхронизации.
  6. Сверить суммы, валюты и периоды; неоднозначные записи отправить на ручную проверку.

Reconciliation замечает новую потерю

Ежедневная сверка сравнивает invoice у провайдера с локальными внешними ключами и создаёт задачи по расхождениям. Метрики полезнее общего «webhook failed»: задержка между `occurred_at` и `recorded_at`, число duplicate events, непривязанные invoice и подписки, где current period не объясняется последней ledger-записью.

Проверка повторяет и переставляет события

В тестовой среде отправьте один `invoice.paid` дважды, затем передайте subscription update после и до него. Во всех вариантах должна появиться ровно одна успешная renewal row, а текущий доступ должен совпасть с authoritative objects. Отдельно проверьте failed payment и ручное продление — они не должны притворяться одним событием.

История считается сохранённой, когда любой видимый период объясняется отдельным фактом, повтор webhook безопасен, а backfill воспроизводим. Для расследования нужны provider event/invoice IDs, периоды, статусы и correlation ID; полные платёжные реквизиты и webhook secret передавать нельзя.

Проверенные источники