Stripe Webhook Event Matrix¶
Last audited: 2026-07-15.
Scope¶
- Endpoint:
/v1/webhooks/stripe - This reflects the current real unified webhook flow.
- If
subscription.local-mock=true, this endpoint accepts requests but does not mutate system state.
Legend¶
| Value | Meaning |
|---|---|
Yes |
Explicitly handled and can change state |
Conditional |
Handled, but only changes state when required context is present |
Partial |
Accepted/routed in some cases, but not fully implemented end-to-end |
No |
Ignored by the current implementation |
Event Matrix¶
| Stripe event | Area | Handled | Affects our system | Current behavior |
|---|---|---|---|---|
checkout.session.completed with mode=subscription |
Subscription | Yes |
Yes |
Activates a new subscription or updates an existing one to ACTIVE. |
checkout.session.completed with mode=payment |
Rent payments | Yes |
Yes |
Updates Stripe attempt state. If payment is final, creates receipt and updates payment request status; otherwise marks the attempt as processing. |
checkout.session.async_payment_succeeded with mode=payment |
Rent payments | Yes |
Yes |
Marks the attempt as succeeded, creates receipt, updates payment request, appends rent-payment event. |
checkout.session.async_payment_failed with mode=payment |
Rent payments | Yes |
Yes |
Marks the attempt as failed, appends rent-payment event, may notify tenant. |
checkout.session.expired |
Rent payments | Yes |
Conditional |
Marks checkout attempt as expired and appends event, but only when linked payment context exists. |
payment_intent.payment_failed |
Rent payments | Yes |
Conditional |
Marks attempt failed, appends event, may notify tenant if linked payment context exists. |
payment_intent.processing |
Rent payments | Yes |
Conditional |
Marks latest Stripe attempt as processing and appends rent-payment event. |
payment_intent.canceled |
Rent payments | Yes |
Conditional |
Marks latest Stripe attempt as canceled and appends rent-payment event. |
payment_intent.succeeded |
Rent payments | Yes |
Conditional |
Marks attempt succeeded. Creates receipt and updates payment request only if full receipt context exists; otherwise snapshot-only. |
account.updated |
Stripe Connect | Yes |
Yes |
Updates connected account readiness flags in the database. |
invoice.paid |
Subscription | Yes |
Yes |
Renews subscription and clears grace period. Also applies pending downgrade on renewal. |
invoice.payment_failed |
Subscription | Yes |
Yes |
Moves subscription to GRACE_PERIOD. |
customer.subscription.deleted |
Subscription | Yes |
Yes |
Sets subscription to CANCELED and disables auto-renew. |
customer.subscription.updated |
Subscription | Yes |
Conditional |
Updates plan, expiry, and/or auto-renew when Stripe payload contains relevant fields such as priceId, periodEnd, or cancelAtPeriodEnd. |
charge.refunded with payment_request_id metadata |
Rent payments | Yes |
Yes |
Appends refund event and can move payment request status back to PARTIALLY_PAID or PENDING. |
charge.refunded without payment_request_id metadata |
Subscription | Yes |
Yes |
Revokes subscription by setting it to REVOKED. |
charge.dispute.created linked to rent payment |
Rent payments | Yes |
Conditional |
Appends dispute event when the dispute can be linked to a payment request or payment intent. |
charge.dispute.updated linked to rent payment |
Rent payments | Yes |
Conditional |
Appends dispute event when linked payment context exists. |
charge.dispute.closed linked to rent payment |
Rent payments | Yes |
Conditional |
Appends dispute event when linked payment context exists. |
charge.dispute.funds_reinstated linked to rent payment |
Rent payments | Yes |
Conditional |
Appends dispute event when linked payment context exists. |
charge.dispute.funds_withdrawn linked to rent payment |
Rent payments | Yes |
Conditional |
Appends dispute event when linked payment context exists. |
charge.dispute.created without rent-payment linkage |
Subscription fallback | Yes |
Conditional |
Resolves the subscription by customer, latest charge, invoice, or payment intent. Current disputes pause the subscription; terminal or stale disputes are accepted without mutation. |
charge.dispute.updated without rent-payment linkage |
None | No |
No |
Ignored. |
charge.dispute.closed without rent-payment linkage |
None | No |
No |
Ignored. |
charge.dispute.funds_reinstated without rent-payment linkage |
None | No |
No |
Ignored. |
charge.dispute.funds_withdrawn without rent-payment linkage |
None | No |
No |
Ignored. |
Any other Stripe event, for example customer.tax_id.created |
None | No |
No |
Logged as unhandled and ignored. |
Important Caveats¶
checkout.session.*events are routed bysession.mode.subscriptionmode goes to subscription flow.paymentmode goes to rent-payment flow.checkout.session.async_payment_succeededandcheckout.session.async_payment_failedare only meaningful in rent-payment flow.- If Stripe ever sends those async checkout events for
subscriptionmode, they are accepted by the dispatcher but become no-ops downstream. - Many rent-payment events are context-dependent.
- If the webhook cannot be linked to a
payment_request_idor resolved viapayment_intent_id, the event is ignored. - Subscription dispute creation is retried when no matching subscription can be resolved.
- The endpoint returns HTTP 500 and records a retryable inbox failure instead of acknowledging an unknown dispute.
customer.subscription.updatedis not guaranteed to change anything.- If Stripe does not send relevant fields, the event is effectively a no-op.
- In mock mode,
subscription.local-mock=truemakes the unified webhook endpoint a no-op.
Triage Checklist¶
When a payment, subscription, dispute, or refund looks wrong:
- Find the Stripe object in Stripe Dashboard.
- Confirm webhook delivery to
/v1/webhooks/stripe. - Check backend logs for the Stripe event id.
- Check New Relic backend for processing exceptions.
- Check CloudWatch Stripe webhook metrics.
- Check whether the event had enough metadata/context to link to a rent payment or subscription.
- Check the final database state for the affected payment request, receipt, subscription, or connected account.