Если обработчик делает только `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
- Сделать резервную копию и выгрузить список затронутых subscription IDs.
- Постранично получить invoice из API провайдера за выбранный период.
- Сопоставить provider customer/subscription с локальной записью.
- Создать отсутствующие ledger rows через ту же idempotent-команду.
- Пометить источник как backfill и сохранить дату синхронизации.
- Сверить суммы, валюты и периоды; неоднозначные записи отправить на ручную проверку.
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 передавать нельзя.