Не открывайте доступ простым UPDATE пользователя. Сначала свяжите paid invoice с customer, subscription и локальным account, затем найдите delivery конкретного webhook event. Ручная правка обойдёт тариф, срок и аудит; штатное повторное применение события либо reconciliation восстановит право так, чтобы следующий webhook не отменил исправление.
Успешная оплата и право доступа — два разных состояния. Биллинг подтверждает деньги и жизненный цикл subscription, а ваше приложение вычисляет entitlement: какой продукт, до какой даты и с какими возможностями доступен. Сбой может быть в доставке webhook, mapping клиента, очереди, бизнес-правиле или кеше уже после правильной записи.
Прослеживаем один invoice от провайдера до интерфейса
| Контрольная точка | Что должно быть | Что означает отсутствие |
|---|---|---|
| Provider invoice | paid=true, subscription reference | Оплата ещё не относится к нужной подписке |
| Webhook delivery | 2xx и event ID | Endpoint не принял или провайдер повторяет |
| Event ledger | Одна запись event ID | Нет дедупликации либо событие потеряно |
| Subscription snapshot | Актуальный допустимый status | Нельзя выдавать право только по старому payload |
| Entitlement row | Product, period, source invoice | Worker не применил правило |
| Session/cache | Новая версия прав | Доступ есть в базе, но UI читает старое |
Stripe рекомендует обрабатывать subscription activity через webhook, потому что значительная часть жизненного цикла асинхронна. Для invoice.paid документация предлагает получить связанную subscription и убедиться, что её status active, прежде чем продлевать срок. Один факт оплаты не всегда описывает итоговое состояние всех счетов и расписаний.
Webhook подтверждает приём, worker меняет доступ
webhook HTTP request
verify signature on raw body
INSERT event_ledger(provider, event_id, type, payload_hash)
ON CONFLICT event_id -> already accepted
enqueue entitlement_reconcile(customer_id, subscription_id)
return 200 quickly
worker
retrieve current subscription
calculate desired entitlements
transaction: upsert rights + access_version + audit
invalidate session/cache after commitStripe требует проверять подпись по raw body и рекомендует быстро вернуть 2xx до тяжёлой обработки. Endpoint может получить одно событие повторно; храните обработанные event IDs. Порядок доставки также не гарантирован, поэтому timestamp события нельзя использовать как единственную защиту от старого состояния — worker получает актуальный объект или запускает расчёт из текущей billing truth.
Почему повтор webhook иногда ничего не исправляет
- Ledger пометил event processed до commit entitlement и теперь отбрасывает повтор.
- Customer ID привязан к старому account после миграции или гостевой покупки.
- Worker продлил subscription_end, но feature entitlement остался от прежнего тарифа.
- События invoice.paid и subscription.updated пришли в неожиданном порядке.
- Cache key не включает access_version либо активная session хранит старые claims.
- Права исправлены, но downstream Discord, LMS или community sync завершился ошибкой.
Состояния event ledger разделяйте на accepted, processing, applied и failed. Processed до фактического commit создаёт потерю. Worker забирает запись с lease, а после сбоя возвращает её в retryable; business error вроде отсутствующего account mapping уходит в quarantine с понятной причиной и не крутится бесконечно.
Reconciliation чинит пропуски без ручной выдачи тарифа
- Выбрать subscriptions, изменённые за безопасное окно, и получить их текущее состояние у провайдера.
- Построить desired entitlements тем же чистым правилом, что использует webhook worker.
- Сравнить desired и actual по account, product, period и feature set.
- Для расхождений создать repair job с причиной и ссылкой на source object.
- Применить изменения идемпотентно и увеличить access_version.
- Отчёт хранит исправленные, спорные и не сопоставленные записи отдельно.
Не вычисляйте доступ как «активен навсегда, если когда-то был invoice.paid». Нужны политика для past_due, unpaid, canceled, refunds и disputes. Stripe отдельно описывает статусы subscription и рекомендует отзывать доступ для unpaid; точное grace period остаётся вашим бизнес-решением и должно быть одинаковым в online worker и reconciliation.
Тест должен пережить повтор, перестановку и задержку
В sandbox оплатите renewal, задержите worker, отправьте invoice.paid дважды и поменяйте порядок с subscription.updated. Затем симулируйте ошибку после записи ledger, но до entitlement commit. В каждом варианте итоговые права должны совпасть с текущей subscription, event ID примениться один раз, а пользователь увидеть новую access_version после commit. Для диагностики достаточно обезличенных provider IDs, event delivery status, mapping и аудита entitlement; платёжные данные не нужны.