Skip to content

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 by session.mode.
  • subscription mode goes to subscription flow.
  • payment mode goes to rent-payment flow.
  • checkout.session.async_payment_succeeded and checkout.session.async_payment_failed are only meaningful in rent-payment flow.
  • If Stripe ever sends those async checkout events for subscription mode, 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_id or resolved via payment_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.updated is 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=true makes the unified webhook endpoint a no-op.

Triage Checklist

When a payment, subscription, dispute, or refund looks wrong:

  1. Find the Stripe object in Stripe Dashboard.
  2. Confirm webhook delivery to /v1/webhooks/stripe.
  3. Check backend logs for the Stripe event id.
  4. Check New Relic backend for processing exceptions.
  5. Check CloudWatch Stripe webhook metrics.
  6. Check whether the event had enough metadata/context to link to a rent payment or subscription.
  7. Check the final database state for the affected payment request, receipt, subscription, or connected account.