Skip to content

Stripe Webhook Event Matrix

Scope

  • Endpoint: /v1/webhooks/stripe
  • This matrix reflects the unified webhook flow.
  • If subscription.local-mock=true, the endpoint accepts requests without mutating system state.

Legend

Value Meaning
Yes Explicitly handled and can change state
Conditional Handled, but changes state only when required context is present
Partial Accepted or routed in some cases, but not fully implemented end to end
No Ignored by the implementation

Event Matrix

Stripe event Area Handled Affects MamNajem 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 the Stripe attempt. A final payment creates a receipt and updates the request; otherwise the attempt remains processing.
checkout.session.async_payment_succeeded with mode=payment Rent payments Yes Yes Marks the attempt succeeded, creates a receipt, updates the request, and appends a payment event.
checkout.session.async_payment_failed with mode=payment Rent payments Yes Yes Marks the attempt failed, appends a payment event, and may notify the tenant.
checkout.session.expired Rent payments Yes Conditional Marks a linked checkout attempt expired and appends an event.
payment_intent.payment_failed Rent payments Yes Conditional Marks a linked attempt failed, appends an event, and may notify the tenant.
payment_intent.processing Rent payments Yes Conditional Marks the latest linked Stripe attempt processing and appends an event.
payment_intent.canceled Rent payments Yes Conditional Marks the latest linked Stripe attempt canceled and appends an event.
payment_intent.succeeded Rent payments Yes Conditional Marks the attempt succeeded. A receipt and request update require complete receipt context; otherwise only the snapshot changes.
account.updated Stripe Connect Yes Yes Updates connected-account readiness flags.
invoice.paid Subscription Yes Yes Renews the subscription, clears grace period, and applies a pending downgrade on renewal.
invoice.payment_failed Subscription Yes Yes Moves the subscription to GRACE_PERIOD.
customer.subscription.deleted Subscription Yes Yes Sets the subscription to CANCELED and disables auto-renew.
customer.subscription.updated Subscription Yes Conditional Updates plan, expiry, or auto-renew when relevant Stripe fields are present.
charge.refunded with payment_request_id metadata Rent payments Yes Yes Appends a refund event and may move the request to PARTIALLY_PAID or PENDING.
charge.refunded without payment_request_id metadata Subscription Yes Yes Revokes the subscription by setting it to REVOKED.
charge.dispute.created linked to rent payment Rent payments Yes Conditional Appends a dispute event when linked payment context can be resolved.
charge.dispute.updated linked to rent payment Rent payments Yes Conditional Appends a dispute event when linked payment context exists.
charge.dispute.closed linked to rent payment Rent payments Yes Conditional Appends a dispute event when linked payment context exists.
charge.dispute.funds_reinstated linked to rent payment Rent payments Yes Conditional Appends a dispute event when linked payment context exists.
charge.dispute.funds_withdrawn linked to rent payment Rent payments Yes Conditional Appends a dispute event when linked payment context exists.
charge.dispute.created without rent-payment linkage Subscription fallback Yes Conditional Resolves a subscription by customer, charge, invoice, or intent. A current dispute pauses it; 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 event, such as customer.tax_id.created None No No Logged as unhandled and ignored.

Important Caveats

  • checkout.session.* events are routed by session.mode: subscription enters subscription handling and payment enters rent-payment handling.
  • Async checkout success and failure events are meaningful only for rent-payment sessions; subscription-mode delivery becomes a downstream no-op.
  • Many rent-payment events require a payment_request_id or resolvable payment_intent_id; an unlinked event is ignored.
  • An unresolved subscription dispute is retryable: the endpoint records inbox failure and returns HTTP 500 rather than acknowledging an unknown dispute.
  • customer.subscription.updated may be a no-op if Stripe supplies no relevant fields.
  • In mock mode, subscription.local-mock=true makes the unified endpoint a no-op.