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 без номера карты и секретов.
Неверную активацию чинят без новой оплаты
- Заморозить автоматические изменения для конфликтующей subscription.
- Подтвердить владельца по истории checkout, billing mapping и данным провайдера.
- Транзакционно погасить ошибочный entitlement и создать правильный с общей correction ID.
- Не менять customer или списание у провайдера, если финансовая связь уже верна.
- Повторно обработать сохранённые события и убедиться, что результат не откатывается.
Для разбора подготовьте event types и IDs, объект subscription без платёжных данных, строки billing_customers и entitlements, а также timeline checkout. По этой цепочке видно, ошибка возникла при выборе организации, создании customer, сопоставлении webhook или ручном исправлении.