Webhooks

Overview

Stripe sends subscription updates through webhook events, this fragment implements a webhook handler for you which keeps the subscription table in sync.

Handled Events

The fragment listens for these subscription-related events:

• checkout.session.completed - Creates the subscription record after successful checkout
• customer.subscription.updated - Updates subscription data when changes occur (renewals, plan changes, etc.)
• customer.subscription.deleted - Removes subscriptions
• customer.subscription.paused - Updates status when subscriptions are paused
• customer.subscription.resumed - Updates status when subscriptions resume
• customer.subscription.trial_will_end - Notifies when trials are ending soon (3 days before)

All of these events automatically update your local subscription table to match the state in Stripe.

Webhook Endpoint URL

The webhook endpoint is available under the {mountPath}/webhook path, for example:

https://yourdomain.com/api/stripe/webhook

Here /api/stripe is the default mount path where you have mounted the Stripe fragment.

Custom Webhook Event Handlers

To implement custom handlers for webhook events supply the fragment with the onEvent callback. This callback is ran before the handlers of the fragment.

export const stripeFragment = createStripeFragment({
  // ... other configs
  onEvent: async ({event}) => {
      switch (event.type) {
          case 'checkout.session.completed':
          // do things
          break;
      }
    }
  }
});

Testing Webhooks Locally

Use the Stripe CLI to forward webhook events to your local server.

stripe listen --forward-to localhost:3000/api/stripe/webhook

Then use the webhook secret provided by the CLI in your fragment config.

When not to rely on webhooks

Webhooks are not guaranteed to be delivered in real-time, therefore there are cases where you may need to get the latest subscription information from Stripe directly. See Manual Synchronization for additional details.