Не открывайте доступ простым UPDATE пользователя. Сначала свяжите paid invoice с customer, subscription и локальным account, затем найдите delivery конкретного webhook event. Ручная правка обойдёт тариф, срок и аудит; штатное повторное применение события либо reconciliation восстановит право так, чтобы следующий webhook не отменил исправление.

Успешная оплата и право доступа — два разных состояния. Биллинг подтверждает деньги и жизненный цикл subscription, а ваше приложение вычисляет entitlement: какой продукт, до какой даты и с какими возможностями доступен. Сбой может быть в доставке webhook, mapping клиента, очереди, бизнес-правиле или кеше уже после правильной записи.

Прослеживаем один invoice от провайдера до интерфейса

Контрольная точкаЧто должно бытьЧто означает отсутствие
Provider invoicepaid=true, subscription referenceОплата ещё не относится к нужной подписке
Webhook delivery2xx и event IDEndpoint не принял или провайдер повторяет
Event ledgerОдна запись event IDНет дедупликации либо событие потеряно
Subscription snapshotАктуальный допустимый statusНельзя выдавать право только по старому payload
Entitlement rowProduct, period, source invoiceWorker не применил правило
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 commit

Stripe требует проверять подпись по 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 чинит пропуски без ручной выдачи тарифа

  1. Выбрать subscriptions, изменённые за безопасное окно, и получить их текущее состояние у провайдера.
  2. Построить desired entitlements тем же чистым правилом, что использует webhook worker.
  3. Сравнить desired и actual по account, product, period и feature set.
  4. Для расхождений создать repair job с причиной и ссылкой на source object.
  5. Применить изменения идемпотентно и увеличить access_version.
  6. Отчёт хранит исправленные, спорные и не сопоставленные записи отдельно.

Не вычисляйте доступ как «активен навсегда, если когда-то был 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; платёжные данные не нужны.

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