Stripe webhook

The Stripe webhook endpoint receives and processes events from Stripe to keep your billing state synchronized.

Endpoint

POST /api/webhook/stripe This endpoint verifies the Stripe signature and handles various billing lifecycle events.

Authentication

This endpoint uses Stripe webhook signature verification instead of user authentication. You must configure the STRIPE_WEBHOOK_SECRET environment variable with your webhook signing secret from the Stripe dashboard.

Headers

string

required

The Stripe webhook signature header for event verification

Request body

The request body is the raw Stripe event payload. Stripe sends different event types with varying data structures.

Supported events

The webhook currently handles these Stripe event types:

checkout.session.completed

Triggered when a customer completes a checkout session.

packages/landing/app/api/webhook/stripe/route.ts

case "checkout.session.completed": {
  const stripeObject: Stripe.Checkout.Session = event.data
    .object as Stripe.Checkout.Session;

  const session = await findCheckoutSession(stripeObject.id);
  const priceId = session?.line_items?.data[0]?.price?.id;
  const plan = configFile.stripe.plans.find(
    (p) => p.priceId === priceId
  );

  if (!plan) break;

  // TODO: Grant access to the product via Supabase
  // const userId = stripeObject.client_reference_id;
  // Update user in Supabase with hasAccess = true, customerId, priceId, etc.

  break;
}

The TODO comments indicate where you should integrate with your Supabase database to grant product access to the user.

checkout.session.expired

Triggered when a checkout session expires without completion.

case "checkout.session.expired":
  // Handle expired checkout sessions
  break;

customer.subscription.updated

Triggered when a subscription is updated (plan change, renewal, etc.).

case "customer.subscription.updated":
  // TODO: Update subscription status in database
  break;

customer.subscription.deleted

Triggered when a subscription is canceled or expires.

case "customer.subscription.deleted": {
  // TODO: Revoke access via Supabase
  break;
}

invoice.paid

Triggered when an invoice payment succeeds (subscription renewal, etc.).

case "invoice.paid": {
  // TODO: Grant access via Supabase
  break;
}

invoice.payment_failed

Triggered when an invoice payment fails.

case "invoice.payment_failed":
  // Handle payment failures (email customer, retry logic, etc.)
  break;

Response

Success (200)

{}

Returns an empty JSON object to acknowledge receipt of the webhook event.

Error (400)

{
  "error": "Webhook signature verification failed. Invalid signature."
}

Returned when the Stripe signature verification fails, indicating the request may not be from Stripe.

Implementation notes

The webhook handler verifies the Stripe signature before processing any events:

packages/landing/app/api/webhook/stripe/route.ts

const body = await req.text();
const signature = (await headers()).get("stripe-signature");

try {
  event = stripe.webhooks.constructEvent(body, signature!, webhookSecret);
} catch (err: any) {
  console.error(`Webhook signature verification failed. ${err.message}`);
  return NextResponse.json({ error: err.message }, { status: 400 });
}

Always verify webhook signatures in production. This prevents unauthorized parties from triggering billing actions in your system.

Setup

1. Configure webhook in Stripe

Go to the Stripe Dashboard → Developers → Webhooks
Click Add endpoint
Enter your webhook URL: https://yourdomain.com/api/webhook/stripe
Select the events you want to receive (or select “all events” for development)
Copy the Signing secret

2. Add environment variable

Add the webhook signing secret to your environment variables:

STRIPE_WEBHOOK_SECRET=whsec_...

3. Test locally with Stripe CLI

Use the Stripe CLI to forward webhook events to your local development server:

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

The CLI will output a webhook signing secret for local testing. Use this in your .env.local file.

4. Trigger test events

stripe trigger checkout.session.completed
stripe trigger customer.subscription.updated
stripe trigger invoice.paid

Integration checklist

The current implementation includes TODO comments where you need to integrate with your database:

checkout.session.completed: Grant product access in Supabase
customer.subscription.updated: Update subscription status
customer.subscription.deleted: Revoke access
invoice.paid: Confirm or extend access
invoice.payment_failed: Notify customer and handle grace period

Store the Stripe customer_id, subscription_id, and price_id in your user profiles table to track billing status.

Security considerations

Signature verification: Always verify the stripe-signature header
Idempotency: Handle duplicate webhook deliveries gracefully
Logging: Log webhook events for debugging and audit trails
Error handling: Return 200 even if your internal processing fails (Stripe will retry)

Billing configuration

Configure Stripe API keys and webhook secrets

Checkout API

Create checkout sessions and customer portals

Overview

Landing API

Supabase API

Stripe webhook

Endpoint

Authentication

Headers

Request body

Supported events

checkout.session.completed

checkout.session.expired

customer.subscription.updated

customer.subscription.deleted

invoice.paid

invoice.payment_failed

Response

Success (200)

Error (400)

Implementation notes

Setup

1. Configure webhook in Stripe

2. Add environment variable

3. Test locally with Stripe CLI

4. Trigger test events

Integration checklist

Security considerations

Billing configuration

Checkout API

​Endpoint

​Authentication

​Headers

​Request body

​Supported events

​checkout.session.completed

​checkout.session.expired

​customer.subscription.updated

​customer.subscription.deleted

​invoice.paid

​invoice.payment_failed

​Response

​Success (200)

​Error (400)

​Implementation notes

​Setup

​1. Configure webhook in Stripe

​2. Add environment variable

​3. Test locally with Stripe CLI

​4. Trigger test events

​Integration checklist

​Security considerations

​Related

Billing configuration

Checkout API

Endpoint

Authentication

Headers

Request body

Supported events

checkout.session.completed

checkout.session.expired

customer.subscription.updated

customer.subscription.deleted

invoice.paid

invoice.payment_failed

Response

Success (200)

Error (400)

Implementation notes

Setup

1. Configure webhook in Stripe

2. Add environment variable

3. Test locally with Stripe CLI

4. Trigger test events

Integration checklist

Security considerations

Related