See Demo
General
Billing

Webhooks

Learn about billing webhook handling.

The starters handles billing webhooks to update customer data based on events received from the billing provider.

Webhook handler

Occasionally, you may need to set up additional webhooks or perform custom actions with webhooks. In such cases, you can customize the billing webhook handler in packages/billing/src/webhook.ts.

packages/billing/src/webhook.ts
const event = await BillingProvider.verifyWebhookSignature(req);
await BillingProvider.handleWebhookEvent(event, {
  onCheckoutSessionCompleted: async (payload) => {
    if ('orderId' in payload) {
      await upsertOrder(payload);
    } else {
      await upsertSubscription(payload);
    }
  },
  onSubscriptionUpdated: async (subscription) => {
    await upsertSubscription(subscription);
  },
  onSubscriptionDeleted: async (subscriptionId) => {
    await deleteSubscription(subscriptionId);
  },
  onPaymentSucceeded: async (sessionId) => {
    await updateOrderStatus(sessionId, 'succeeded');
  },
  onPaymentFailed: async (sessionId) => {
    await updateOrderStatus(sessionId, 'failed');
  },
  onCustomerCreated: async (customer) => {
    await upsertCustomer(customer);
  },
  onCustomerUpdated: async (customer) => {
    await upsertCustomer(customer);
  },
  onCustomerDeleted: async (customerId) => {
    await deleteCustomer(customerId);
  }
});

Events

The corresponding Stripe events are:

  • checkout.session.completed
  • customer.subscription.updated
  • customer.subscription.deleted
  • checkout.session.async_payment_failed
  • checkout.session.async_payment_succeeded
  • customer.created
  • customer.updated
  • customer.deleted

This means that we ingest

  • checkouts
  • subscriptions and subscription items
  • orders and order items
  • customers