- Stripe webhooks are POST requests Stripe sends to your server when something happens: a payment succeeds, a subscription renews, a card fails. - Without webhooks, your app has no way to know any of this happened. Your database will go out of sync with Stripe. - The events that matter for a SaaS: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_succeeded`, `invoice.payment_failed`. - Always verify the webhook signature. Never trust the payload without it. - Stripe retries failed webhooks for up to 3 days in live mode with exponential backoff. In sandbox it retries 3 times over a few hours. Handle idempotency so processing the same event twice doesn't break anything. - Never return a non-200 response unless the request itself is invalid. Handle errors inside your logic, not at the HTTP level.

## The Stripe Payment Flow: How It Actually Works Before getting into webhooks, it helps to understand the full Stripe payment flow and where webhooks fit in it. When a user clicks "Subscribe" on your pricing page, here is what happens in order: **1. Your app creates a Checkout Session** You call the Stripe API server-side and create a Checkout Session. This is a temporary object that represents an in-progress checkout. Stripe returns a URL. You redirect the user to it. **2. The user completes checkout on Stripe's hosted page** Stripe handles everything: card collection, 3D Secure authentication, fraud detection, currency conversion. Your app is not involved in this step at all. **3. Stripe redirects the user back to your success URL** Once checkout completes, Stripe redirects the user to the `success_url` you provided when creating the session. This might be `/dashboard?session_id=...` or similar. **4. Stripe sends a webhook event to your server** At roughly the same time as the redirect, Stripe fires a POST request to your webhook endpoint. This is how your backend finds out the payment actually went through. Here is where most developers make their first mistake: they try to provision access or update the database based on the redirect back to the success URL. This is wrong for two reasons. The user can land on the success URL without completing payment (by navigating directly to it). And the redirect happens client-side, which means it can be blocked, the tab can be closed, or the network can fail before your server knows anything happened. Webhooks are the source of truth. The redirect is just the user experience. Your database should only update when the webhook fires.

## What Are Stripe Webhooks? A webhook is an HTTP POST request that Stripe sends to a URL you control when an event occurs in your Stripe account. You register the URL in the Stripe dashboard. When something happens — a payment succeeds, a subscription renews, a dispute is opened — Stripe sends a JSON payload to that URL describing the event. Your server receives the payload, verifies it came from Stripe, and runs whatever business logic is appropriate: update the user's subscription status in your database, send a confirmation email, provision access to a feature. The payload looks like this: ```json { "id": "evt_1OqPjQ2eZvKYlo2C9VbK7n0Q", "object": "event", "type": "checkout.session.completed", "created": 1709123456, "data": { "object": { "id": "cs_test_a1b2c3d4e5f6", "customer": "cus_OqPjQ2eZvKYlo2C", "subscription": "sub_1OqPjQ2eZvKYlo2C", "metadata": { "userId": "user_abc123" } } } } ``` Every event has a `type` field that tells you what happened, and a `data.object` field that contains the relevant Stripe object. Your webhook handler switches on the `type` and handles each event appropriately. Stripe retries failed webhook deliveries with exponential backoff for up to 3 days in live mode. In sandbox, Stripe retries 3 times over a few hours. It also means you need to handle receiving the same event more than once — which is where idempotency comes in.

## Which Stripe Webhook Events Actually Matter for a SaaS Stripe has over 200 event types. Most of them are not relevant to a typical SaaS. Here are the ones you need to handle, what they mean, and what your app should do when they fire.

## `checkout.session.completed` **When it fires:** The user successfully completed a Stripe Checkout session. Payment was collected or a free trial was started. **What it means:** A new subscription was created. This is the moment your app should provision access. **What to do:** - Extract the `customer` ID and `subscription` ID from the session - Extract the `userId` from `metadata` (you pass this when creating the session) - Update your database: set `stripeCustomerId`, `stripeSubscriptionId`, and `subscriptionStatus` to `active` on the user's record - Send a welcome email **Why it matters:** Without handling this event, users who complete checkout have no access to your product. This is the most important webhook for any SaaS. ```ts case "checkout.session.completed": { const session = event.data.object as Stripe.Checkout.Session; const userId = session.metadata?.userId; const customerId = session.customer as string; const subscriptionId = session.subscription as string; await db.users.update({ where: { id: userId }, data: { stripeCustomerId: customerId, stripeSubscriptionId: subscriptionId, subscriptionStatus: "active", }, }); break; } ```

## `customer.subscription.updated` **When it fires:** A subscription changed. This includes plan upgrades, downgrades, trial conversions, pausing, and any change to subscription metadata. **What it means:** The user's subscription is in a different state than before. Your database needs to reflect the new state. **What to do:** - Check `subscription.status` on the event object — it can be `active`, `trialing`, `past_due`, `canceled`, `unpaid`, `incomplete` (initial payment failed), or `incomplete_expired` (initial payment not paid within 23 hours). `paused` occurs only when a trial ends without a payment method on file. - Update your database with the new status - If the plan changed (different `price.id`), update which plan the user is on - If `cancel_at_period_end` is `true`, the user has scheduled a cancellation but still has access until the period ends **Why it matters:** This is the event that handles plan changes and trial-to-paid conversions. A user who upgrades from a free trial expects their new features immediately. This webhook is how that happens. ```ts case "customer.subscription.updated": { const subscription = event.data.object as Stripe.Subscription; const customerId = subscription.customer as string; await db.users.update({ where: { stripeCustomerId: customerId }, data: { subscriptionStatus: subscription.status, cancelAtPeriodEnd: subscription.cancel_at_period_end, currentPeriodEnd: new Date(subscription.current_period_end * 1000), }, }); break; } ```

## `customer.subscription.deleted` **When it fires:** A subscription was cancelled and the billing period ended. This fires at the end of the final period, not when the user clicks cancel. **What it means:** The user's access should be revoked. They are no longer a paying customer. **What to do:** - Set `subscriptionStatus` to `canceled` in your database - Remove access to paid features - Optionally trigger a win-back email sequence **Why it matters:** This is how you revoke access when someone cancels. Missing this event means canceled users keep their access indefinitely. ```ts case "customer.subscription.deleted": { const subscription = event.data.object as Stripe.Subscription; const customerId = subscription.customer as string; await db.users.update({ where: { stripeCustomerId: customerId }, data: { subscriptionStatus: "canceled", stripeSubscriptionId: null, }, }); break; } ```

## `invoice.payment_succeeded` **When it fires:** An invoice was paid. This fires on the initial subscription payment and on every subsequent renewal. **What it means:** A payment came through successfully. If the account was `past_due` because a previous payment failed, this event means they are back in good standing. **What to do:** - Reset any `past_due` flags on the user's account - Update `currentPeriodEnd` with the new period end date from the invoice - Log the payment for your own records - Optionally send a receipt email (though Stripe can do this automatically from the dashboard) **Why it matters:** Subscription renewals are invisible without this event. You need to know each renewal succeeded so you can keep access active and track revenue accurately. ```ts case "invoice.payment_succeeded": { const invoice = event.data.object as Stripe.Invoice; const customerId = invoice.customer as string; const subscriptionId = invoice.subscription as string; await db.users.update({ where: { stripeCustomerId: customerId }, data: { subscriptionStatus: "active", lastPaymentAt: new Date(), }, }); break; } ```

## `invoice.payment_failed` **When it fires:** A payment attempt for an invoice failed. Stripe uses Smart Retries (ML-based) to automatically retry failed payments. By default Stripe retries up to 8 times within 2 weeks, though this is configurable in your Stripe dashboard under Settings > Billing > Revenue Recovery. `invoice.payment_failed` fires on **every retry attempt**, not just the first failure. **What it means:** The user's card was declined. If all retries are exhausted, the subscription will move to `canceled` or `unpaid` depending on your Stripe dunning settings. **What to do:** - Set `subscriptionStatus` to `past_due` in your database - Send a dunning email asking them to update their payment method — but deduplicate by invoice ID, not by event. Since this event fires on every retry attempt, triggering an email on every event would spam your users. Send the first email on the initial failure, then space follow-ups manually - Consider showing an in-app banner when they log in while `past_due` - Do not immediately revoke access — give them time to fix it **Why it matters:** Failed payments are the most common source of involuntary churn. Handling this event and prompting users to update their card recovers a meaningful percentage of revenue that would otherwise be lost silently. ```ts case "invoice.payment_failed": { const invoice = event.data.object as Stripe.Invoice; const customerId = invoice.customer as string; await db.users.update({ where: { stripeCustomerId: customerId }, data: { subscriptionStatus: "past_due" }, }); // Send dunning email await sendPaymentFailedEmail(customerId); break; } ```

## `customer.subscription.trial_will_end` **When it fires:** 3 days before a trial period ends. Only fires if you are using Stripe trials. **What it means:** The user's trial is ending soon. If they haven't added a payment method, they may lose access. **What to do:** - Send a reminder email prompting them to add a card if they haven't already - Show an in-app banner counting down the trial **Why it matters:** Trial-to-paid conversion is where most SaaS revenue comes from. A well-timed reminder significantly improves conversion rates.

## Setting Up Stripe Webhooks in Next.js Now that you know which events to handle and why, here is the full implementation for a Next.js 16 App Router project. ### Step 1: Install the Stripe SDK ```bash npm install stripe ``` ### Step 2: Set Up Environment Variables ```bash # .env.local STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx ``` The `STRIPE_WEBHOOK_SECRET` comes from the Stripe dashboard after you create a webhook endpoint, or from the Stripe CLI during local development. ### Step 3: Create a Reusable Stripe Client ```ts // lib/stripe.ts import Stripe from "stripe"; export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2026-05-27.dahlia", typescript: true, }); ``` ### Step 4: Create the Webhook Route Handler This is the most important file. A few things to pay attention to: - You must read the raw request body as text, not JSON. Stripe's signature verification requires the exact raw bytes. In Next.js App Router Route Handlers, simply use `await req.text()` — no body parser configuration is needed. - Return a 200 immediately after handling. Stripe considers anything other than a 2xx response as a failure and will retry. ```ts // app/api/webhooks/stripe/route.ts import { NextRequest, NextResponse } from "next/server"; import { stripe } from "@/lib/stripe"; import Stripe from "stripe"; async function handleCheckoutCompleted(session: Stripe.Checkout.Session) { const userId = session.metadata?.userId; if (!userId) throw new Error("Missing userId in session metadata"); await db.users.update({ where: { id: userId }, data: { stripeCustomerId: session.customer as string, stripeSubscriptionId: session.subscription as string, subscriptionStatus: "active", }, }); } async function handleSubscriptionUpdated(subscription: Stripe.Subscription) { await db.users.update({ where: { stripeCustomerId: subscription.customer as string }, data: { subscriptionStatus: subscription.status, cancelAtPeriodEnd: subscription.cancel_at_period_end, currentPeriodEnd: new Date(subscription.current_period_end * 1000), }, }); } async function handleSubscriptionDeleted(subscription: Stripe.Subscription) { await db.users.update({ where: { stripeCustomerId: subscription.customer as string }, data: { subscriptionStatus: "canceled", stripeSubscriptionId: null, }, }); } async function handlePaymentSucceeded(invoice: Stripe.Invoice) { await db.users.update({ where: { stripeCustomerId: invoice.customer as string }, data: { subscriptionStatus: "active", lastPaymentAt: new Date(), }, }); } async function handlePaymentFailed(invoice: Stripe.Invoice) { await db.users.update({ where: { stripeCustomerId: invoice.customer as string }, data: { subscriptionStatus: "past_due" }, }); } export async function POST(req: NextRequest) { const body = await req.text(); const signature = req.headers.get("stripe-signature"); if (!signature) { return NextResponse.json( { error: "Missing stripe-signature header" }, { status: 400 } ); } let event: Stripe.Event; try { event = stripe.webhooks.constructEvent( body, signature, process.env.STRIPE_WEBHOOK_SECRET! ); } catch (err) { console.error("[stripe webhook] signature verification failed:", err); return NextResponse.json( { error: "Invalid signature" }, { status: 400 } ); } try { switch (event.type) { case "checkout.session.completed": await handleCheckoutCompleted( event.data.object as Stripe.Checkout.Session ); break; case "customer.subscription.updated": await handleSubscriptionUpdated( event.data.object as Stripe.Subscription ); break; case "customer.subscription.deleted": await handleSubscriptionDeleted( event.data.object as Stripe.Subscription ); break; case "invoice.payment_succeeded": await handlePaymentSucceeded(event.data.object as Stripe.Invoice); break; case "invoice.payment_failed": await handlePaymentFailed(event.data.object as Stripe.Invoice); break; default: console.log(`[stripe webhook] unhandled event type: ${event.type}`); } } catch (err) { console.error(`[stripe webhook] error handling ${event.type}:`, err); // Still return 200 — we received the event, processing failed internally // Log to your error tracking (Sentry, etc.) and investigate return NextResponse.json({ received: true }, { status: 200 }); } return NextResponse.json({ received: true }, { status: 200 }); } ``` ### Step 5: Pass userId in Checkout Session Metadata When you create the checkout session, pass the user's ID in metadata. This is how your webhook knows which user just subscribed. ```ts // app/actions/billing.ts "use server"; import { stripe } from "@/lib/stripe"; import { getUser } from "@/lib/auth"; export async function createCheckoutSession(priceId: string) { const user = await getUser(); const session = await stripe.checkout.sessions.create({ mode: "subscription", line_items: [{ price: priceId, quantity: 1 }], metadata: { userId: user.id, // this shows up in checkout.session.completed }, success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?success=true`, cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`, }); return { url: session.url }; } ``` ### Step 6: Register the Webhook Endpoint in Stripe **For local development:** Install the Stripe CLI and run: ```bash stripe listen --forward-to localhost:3000/api/webhooks/stripe ``` This forwards Stripe events to your local server. The CLI outputs a webhook signing secret starting with `whsec_` — put that in your `.env.local` as `STRIPE_WEBHOOK_SECRET`. **For production:** Go to the Stripe Dashboard, navigate to Developers > Webhooks, click Add endpoint, and enter your production URL: `https://yourdomain.com/api/webhooks/stripe`. Select the events you want to listen for: - `checkout.session.completed` - `customer.subscription.updated` - `customer.subscription.deleted` - `invoice.payment_succeeded` - `invoice.payment_failed` - `customer.subscription.trial_will_end` Stripe will show you the webhook signing secret for this endpoint — add it to your production environment variables.

## Idempotency: Handling Duplicate Events Stripe guarantees at-least-once delivery. In rare cases, the same event can be delivered more than once. If your webhook handler is not idempotent, processing the same event twice could create duplicate database records, send duplicate emails, or provision access multiple times. The simplest approach is to store the Stripe event ID and skip processing if you've seen it before: ```ts // Check if we've already processed this event const existing = await db.stripeEvents.findUnique({ where: { stripeEventId: event.id }, }); if (existing) { console.log(`[stripe webhook] already processed event ${event.id}, skipping`); return NextResponse.json({ received: true }, { status: 200 }); } // Process the event // ... // Mark as processed await db.stripeEvents.create({ data: { stripeEventId: event.id, processedAt: new Date() }, }); ``` You need a `stripeEvents` table in your database with a `stripeEventId` column. A simple schema: ```sql create table stripe_events ( id uuid primary key default gen_random_uuid(), stripe_event_id text unique not null, processed_at timestamptz default now() ); ```

## Common Mistakes **Reading the body as JSON instead of text** Stripe's signature verification requires the raw request body bytes. Parsing it as JSON first changes the byte content and makes verification fail. Always use `await req.text()` and pass the string directly to `stripe.webhooks.constructEvent`. **Returning 4xx for business logic errors** If your database update fails or an email fails to send, do not return a 4xx response. Stripe will retry the webhook, which may cause duplicate processing. Instead, catch the error internally, log it, and still return 200. Fix the underlying problem through your error tracking, not through retries. **Sending a dunning email on every `invoice.payment_failed` event** This event fires on every retry attempt, not just the first failure. If Stripe retries 8 times over 2 weeks and you send an email each time, you'll spam your user into churning faster. Deduplicate by invoice ID — send the first email on the initial failure, then control your own follow-up cadence separately from Stripe's retry schedule. **Not passing userId in metadata** When `checkout.session.completed` fires, the only way to know which user just subscribed is if you passed their ID in the session metadata when creating the checkout session. Forget to do this and you have a payment with no way to match it to a user. **Trusting the redirect instead of the webhook** Never provision access on the `success_url` redirect. Users can navigate directly to your success URL. Stripe can redirect before your server gets the webhook. The redirect is UX. The webhook is the source of truth. **Not verifying the signature** Anyone can POST to your webhook endpoint. Without signature verification, an attacker could send fake events to provision access for free or trigger other unintended behavior. Always call `stripe.webhooks.constructEvent` and handle the error if it throws. **Not handling `customer.subscription.updated` for trial conversions** When a free trial converts to a paid subscription, Stripe fires `customer.subscription.updated` with the new status, not a new `checkout.session.completed`. If you only listen for checkout events, trial conversions will silently fail to update your database.

## Testing Webhooks Locally The Stripe CLI is the right tool for local webhook testing: ```bash # Install the CLI brew install stripe/stripe-cli/stripe # Login to your Stripe account stripe login # Forward events to your local server stripe listen --forward-to localhost:3000/api/webhooks/stripe # In another terminal, trigger a specific event stripe trigger checkout.session.completed stripe trigger invoice.payment_failed stripe trigger customer.subscription.deleted ``` The CLI prints each event as it arrives, so you can see exactly what payload your handler receives. It also lets you replay specific events from your Stripe dashboard, which is useful when debugging a handler that failed in production.

## Wrap Up Stripe webhooks are the backbone of any SaaS billing integration. Without them, your database falls out of sync with Stripe the moment anything happens after the initial checkout: a renewal, a failed payment, a plan change, a cancellation. The five events that matter for most SaaS products are `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_succeeded`, and `invoice.payment_failed`. Handle those five and you have a complete billing loop. The three rules that keep your webhook handler reliable: verify the signature on every request, return 200 even when your internal logic fails, and handle duplicate events with idempotency checks. If you're building a SaaS and want your project management, deployment tracking, and analytics in one place so you can focus on shipping rather than tab switching, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## What are Stripe webhooks? Stripe webhooks are HTTP POST requests that Stripe sends to a URL you control when an event occurs in your Stripe account. When a payment succeeds, a subscription renews, or a card fails, Stripe fires a webhook event containing a JSON payload that describes what happened. Your server receives the event and runs the appropriate business logic: updating your database, sending emails, provisioning access. Without webhooks, your app has no way to know when these events occur. ## Which Stripe webhook events do I need for a SaaS? The five essential webhook events for a SaaS are: `checkout.session.completed` (provision access after signup), `customer.subscription.updated` (handle plan changes and trial conversions), `customer.subscription.deleted` (revoke access after cancellation), `invoice.payment_succeeded` (confirm renewals), and `invoice.payment_failed` (handle failed payments and send dunning emails). You should also handle `customer.subscription.trial_will_end` if you use Stripe trials. ## How do I verify Stripe webhook signatures in Next.js? Use `stripe.webhooks.constructEvent(body, signature, webhookSecret)`. The `body` must be the raw request body as a string — not parsed JSON. The `signature` comes from the `stripe-signature` request header. The `webhookSecret` is the signing secret from your Stripe dashboard or CLI. If verification fails, `constructEvent` throws an error. Return a 400 response in that case and do not process the event. ## Why is my Stripe webhook signature verification failing? The most common cause is reading the request body as JSON before passing it to `constructEvent`. Parsing JSON changes the byte representation and breaks the signature check. Always read the body as raw text with `await req.text()`. Other causes include using the wrong webhook secret (the dashboard secret and the CLI secret are different), or middleware that reads and modifies the request body before your handler runs. ## How do I test Stripe webhooks locally? Install the Stripe CLI, run `stripe login` to authenticate, then run `stripe listen --forward-to localhost:3000/api/webhooks/stripe`. The CLI forwards Stripe events to your local server and outputs a webhook signing secret to use in your `.env.local`. In a separate terminal, trigger specific events with `stripe trigger checkout.session.completed` or any other event type. This simulates real Stripe events without going through a real checkout flow. ## How do I handle duplicate Stripe webhook events? Stripe guarantees at-least-once delivery, so the same event can arrive more than once. Handle this by storing the Stripe event ID in a database table after processing, and checking for it at the start of every webhook handler. If the event ID already exists in your table, return 200 immediately without reprocessing. This makes your handler idempotent and safe to receive the same event multiple times. ## Should I return a 200 or 500 if my webhook handler throws an error? Return 200 even if your internal logic fails. If you return a non-200 response, Stripe will retry the webhook, which can cause duplicate processing of the same event. Instead, catch errors internally, log them to your error tracking tool (Sentry or similar), and still return 200. Investigate and fix the underlying issue through your logs, not through Stripe retries. The only time to return a 4xx is if the request itself is invalid — for example, missing the `stripe-signature` header or failing signature verification.