Skip to Content

Payment webhooks

Modem manages the Stripe webhook for a project’s billing connection. Connecting or updating Stripe creates or repairs the endpoint while retaining its server-managed account, signing and API-version settings. Use the connection workflow to repair a broken configuration rather than editing signing fields independently.

Events and verification

The configured events cover Checkout completion, expiry and asynchronous payment results; invoice payment results; subscription changes and deletion, including pending changes; and refunds. Modem checks the signature and Live/Sandbox mode before recording receipt. A delivery for a different mode does not grant access to this project.

An invoice payment failure is nonterminal: it is not treated as proof that the subscription is permanently canceled. See billing and access for access-ended and provider-final states.

Received does not mean processed

A successful response with received: true acknowledges a stored webhook receipt. The associated grant, upgrade, cancellation or refund may still be processing or awaiting retry. Duplicate event IDs are deduplicated; repeated delivery is not meant to create another grant.

Check both sides when debugging:

  1. In Stripe, verify the intended endpoint received the expected event in the correct account and mode.
  2. In Modem, inspect the project’s stored checkout details and the customer’s payment/grant history.
  3. Compare payment references and timestamps. A webhook receipt can precede the visible business-state update.
  4. Resolve credential, ownership or unsupported-payment errors before retrying the same business operation.

Do not create a new checkout or refund solely because a webhook has been acknowledged but access has not updated yet.

Local and production delivery

A locally reachable docs or app URL is not automatically reachable from Stripe. Webhook delivery requires a supported reachable app endpoint in the environment under test. The documentation build does not establish that a local payment integration is connected.

After moving from test keys to live keys, verify live-mode delivery separately. Preserve the correct account and mode for historical payments and refunds.

Last updated on