Webhook приходит без контекста браузерной вкладки, поэтому активировать подписку для «текущего пользователя» нельзя. Надёжное основание — customer платёжного провайдера, заранее связанный с конкретным локальным account. Сначала найдите эту связь, затем создайте или обновите entitlement этого account.

Разберите один инцидент от конца к началу: какой локальный аккаунт получил доступ, какой subscription ID записан, каков customer у этой подписки и кто создал checkout. Email полезен оператору, но не является стабильным ключом: адрес меняется, повторяется у членов команды и может отличаться в платёжной форме.

Четыре идентификатора отвечают за разные сущности

ИдентификаторЧто обозначаетГде использовать
user_idЧеловека, который вошёлАудит инициатора checkout
account_idОрганизацию или тарифный контурВладелец entitlement
provider_customer_idПлательщика у провайдераПостоянная billing-связь
subscription_idКонкретную подпискуСтатус, период и события жизненного цикла

Stripe указывает customer прямо в объекте Subscription и требует, чтобы default payment method принадлежал этому customer. Локальная модель должна отражать ту же связь. Если один пользователь управляет двумя организациями, выбор account фиксируется на сервере до создания checkout и затем не выводится заново из активной вкладки.

Billing mapping появляется до перехода к оплате

billing_customers(
  provider, provider_customer_id, account_id, created_at
)

UNIQUE(provider, provider_customer_id)
UNIQUE(provider, account_id)

entitlements(account_id, subscription_id, state, valid_until)

Если бизнес разрешает несколько customer для одного account, второе ограничение меняют осознанно и добавляют признак активной связи. Но одна provider customer identity не должна владеть двумя локальными account без отдельной модели совместного биллинга. Конфликт останавливает обработку и попадает в ручную очередь.

Webhook сначала подтверждает источник, потом меняет доступ

  • Проверить подпись по сырому телу запроса и актуальному webhook secret.
  • Зафиксировать event ID и тип до выполнения бизнес-операции.
  • Загрузить subscription/customer из проверенного payload или API провайдера.
  • Найти account только через billing mapping и проверить отсутствие конфликта.
  • В одной транзакции обновить subscription state, entitlement и processed event.

Stripe предупреждает, что события могут приходить повторно и не гарантирует их порядок. UNIQUE по provider event ID закрывает дубль, а переходы состояния сравнивают период и актуальный объект, а не слепо применяют последнюю доставленную строку. Быстрый HTTP-ответ отделяют от долгой фоновой обработки.

Metadata помогает расследовать, но не заменяет проверку

Можно сохранить account ID в metadata или client reference при создании checkout. Это удобно для корреляции, но входные данные всё равно проверяются против серверной billing-связи. Нельзя разрешать произвольный account_id из формы: пользователь способен изменить request или повторить старую ссылку.

Ключ идемпотентности защищает создание customer или subscription при сетевом retry. Он не решает ошибочный выбор account — этот выбор должен быть подтверждён до внешнего POST. В журнале храните operation ID, account ID и provider object IDs без номера карты и секретов.

Неверную активацию чинят без новой оплаты

  1. Заморозить автоматические изменения для конфликтующей subscription.
  2. Подтвердить владельца по истории checkout, billing mapping и данным провайдера.
  3. Транзакционно погасить ошибочный entitlement и создать правильный с общей correction ID.
  4. Не менять customer или списание у провайдера, если финансовая связь уже верна.
  5. Повторно обработать сохранённые события и убедиться, что результат не откатывается.

Для разбора подготовьте event types и IDs, объект subscription без платёжных данных, строки billing_customers и entitlements, а также timeline checkout. По этой цепочке видно, ошибка возникла при выборе организации, создании customer, сопоставлении webhook или ручном исправлении.

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