Test Stripe Webhooks Locally: CLI Forwarding, Triggers and Traps

To test a Stripe webhook locally, run stripe listen --forward-to localhost:3000/api/webhooks/stripe, copy the whsec_ signing secret it prints into your app's environment, then fire events with stripe trigger or a real checkout in a sandbox. The Stripe CLI receives events over a direct connection to Stripe and replays each one to your local route, so you need no public URL, no tunnel and no endpoint registered in the Dashboard.

Commands and flags checked October 2026 against Stripe's docs for webhooks, stripe listen, stripe trigger, stripe fixtures, stripe events resend, signature errors and event formats, with Stripe CLI v1.53.1 (released October 7, 2026) as the current release. The route follows Stripe's own Next.js App Router example.

Webhooks are where a payment becomes a plan change in your database, which makes them the part of billing you least want to debug in production. This tutorial builds the whole local loop and then covers the four ways forwarding fails without telling you. It belongs to our hub on how to build an AI SaaS, where checkout and webhooks are week four of the build order.

What will you have at the end?

Three terminal tabs and a loop you can run in seconds: your app, the CLI forwarding events to it, and a third tab for firing them. Every event Stripe would send in production reaches your route with a valid signature.

What do you need before you start?

The fifth item is new enough to catch people. Stripe's CLI reference says that for CLI versions newer than v1.50.0, an Administrator or IAM Admin must enable CLI access for the account before stripe login will authenticate. On your own account, that admin is you.

How do you test a Stripe webhook locally, step by step?

Step 1: install the CLI and log in

npm install -g @stripe/cli
stripe login
stripe login list

Stripe's docs install the CLI with npm; the CLI readme also lists brew install stripe for macOS and winget install Stripe.StripeCLI for Windows. stripe login shows a pairing code and opens the Dashboard, where you approve access and choose which accounts and sandboxes the CLI may use. Expected result: stripe login list marks one account or sandbox as active. It must be the one your app's API key belongs to; if it is not, run stripe switch.

Step 2: add a route that verifies the signature

In the Next.js App Router, a webhook is a Route Handler. This one is Stripe's example with the handler trimmed to a single event type:

// app/api/webhooks/stripe/route.ts
import { Stripe } from 'stripe'
import { NextResponse } from 'next/server'
import { headers } from 'next/headers'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string)

export async function POST(req: Request) {
  let event: Stripe.Event

  try {
    const signature = (await headers()).get('stripe-signature')
    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET
    if (!webhookSecret) throw new Error('STRIPE_WEBHOOK_SECRET is not set')

    // The raw body, exactly as Stripe sent it. Not req.json().
    event = stripe.webhooks.constructEvent(
      await req.text(),
      signature as string,
      webhookSecret
    )
  } catch (err) {
    const message = err instanceof Error ? err.message : 'Unknown error'
    console.error('Webhook signature check failed: ' + message)
    return NextResponse.json({ message: 'Webhook Error: ' + message }, { status: 400 })
  }

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session
      console.log('Checkout completed', session.id, session.client_reference_id)
      // Look up your user and update their plan here.
      break
    }
    default:
      console.log('Unhandled event type ' + event.type)
  }

  return NextResponse.json({ message: 'Received' }, { status: 200 })
}

constructEvent takes three things: the raw request body, the Stripe-Signature header and the endpoint secret. If any of the three is wrong it throws, and the route answers 400. What this protects: nobody can post a fake "payment succeeded" to your route without the secret. What it does not: it does not stop duplicates or out-of-order delivery, and it says nothing about whether your handler did the right thing with a real event.

Step 3: run stripe listen and store the secret

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

> Ready! Your webhook signing secret is whsec_... (^C to quit)

Leave it running. Copy the secret into the file your app reads its environment from:

# .env.local
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Expected result: the "Ready!" line, and no error from your route about a missing secret. Two facts save repeated copying: Stripe's reference says this secret does not change between restarts of stripe listen, and stripe listen --print-secret prints it without starting a session. It is not the secret of any endpoint in your Dashboard, so do not reuse it in production.

Step 4: fire an event

stripe trigger checkout.session.completed

Expected result: the trigger tab prints a "Setting up fixture for" line per step and ends with "Trigger succeeded!". The listen tab shows several events, not one, because the fixture creates a product, a price, a Checkout Session and a payment on the way; each line is followed by the status code your route returned. Your server log shows the checkout.session.completed branch running.

Stripe's docs are explicit that this is not a simulation: triggers issue real API requests in your sandbox and create every object along the way. That is useful, because the events are genuine, and it is why your sandbox fills with products called "myproduct".

stripe listen local webhook: which flags matter?

stripe listen with only --forward-to sends your route every snapshot event in the sandbox. That is fine on day one and noisy by day three. These are the flags worth knowing:

Filtering to the events your production endpoint will subscribe to keeps local behaviour honest. Stripe recommends listening only to the event types an integration needs, and a typical subscription product needs about five:

stripe listen \
  --events checkout.session.completed,customer.subscription.updated,customer.subscription.deleted,invoice.paid,invoice.payment_failed \
  --forward-to localhost:3000/api/webhooks/stripe

stripe trigger webhook: how do you send custom payloads?

A stock trigger proves the plumbing. It does not prove your logic, because the objects it creates know nothing about your users. The built-in checkout.session.completed fixture, for instance, creates a one-off payment session with no client_reference_id and no metadata, so a handler that looks up a user by either finds nobody.

Three flags change what a trigger sends. They address a step in the fixture by name, then a parameter path:

# Attach your own user ID so the handler has something to look up
stripe trigger checkout.session.completed \
  --add checkout_session:client_reference_id=user_123

# Change a value the fixture already sets
stripe trigger checkout.session.completed \
  --override "checkout_session:line_items[0].quantity=10"

# Open the fixture in your editor before it runs
stripe trigger customer.subscription.created --edit

• --add sets a parameter the fixture does not have. This is the one you will use most.
• --override replaces a value the fixture sets; quote it when the path contains brackets.
• --remove drops a parameter, and --skip skips a whole step.
• --edit opens the fixture in your editor instead, and cannot be combined with the others.

stripe trigger --help lists every supported event. For flows a fixture cannot express well, such as a subscription started through your own pricing page, skip the trigger and run the real thing: open your checkout in the browser and pay with Stripe's test card 4242 4242 4242 4242, any future expiry date and any three-digit CVC. With stripe listen running, the events arrive exactly as they will in production, carrying the IDs your own code attached.

How do you seed data and replay events?

stripe fixtures runs a JSON file of API requests in order, and lets later requests reference earlier responses. It is the tool for repeatable seed data: a customer that maps to a user in your local database, on a plan that looks like yours. This file adapts the CLI's own subscription fixture and adds the metadata a handler would read:

{
  "_meta": { "template_version": 0 },
  "fixtures": [
    {
      "name": "customer",
      "path": "/v1/customers",
      "method": "post",
      "params": {
        "email": "seed-user@example.com",
        "metadata": { "user_id": "user_123" },
        "payment_method": "pm_card_visa",
        "invoice_settings": { "default_payment_method": "pm_card_visa" }
      }
    },
    {
      "name": "product",
      "path": "/v1/products",
      "method": "post",
      "params": { "name": "Pro plan (seed)" }
    },
    {
      "name": "price",
      "path": "/v1/prices",
      "method": "post",
      "params": {
        "product": "${product:id}",
        "unit_amount": "1900",
        "currency": "usd",
        "recurring[interval]": "month"
      }
    },
    {
      "name": "subscription",
      "path": "/v1/subscriptions",
      "method": "post",
      "params": {
        "customer": "${customer:id}",
        "items": [{ "price": "${price:id}" }]
      }
    }
  ]
}

stripe fixtures ./seed-subscription.json

# Replay one of the events it produced to your local route
stripe events resend evt_...

Running it produces the real sequence a new subscriber generates, including customer.subscription.created and invoice.paid. Then use stripe events resend with an event ID from the listen tab to deliver the same event again. Stripe says endpoints will occasionally receive duplicates and that events are not delivered in a fixed order, so a handler that passes this replay test is one you can trust.

The four failure modes that make forwarding silently fail

Signature errors are loud: you get a 400 and a message. These four are quiet. Nothing errors, and nothing happens.

A few details on each. Sandboxes: objects in one sandbox are invisible to another, and Stripe now recommends general sandboxes over the older test mode sandbox for new integrations, so it is easy to have a key from one and a CLI session in the other. Filters: thin events are never forwarded unless you ask for them, which matters if you follow Stripe's current advice for new handlers.

Reachability: in a Next.js app the usual culprit is auth. A proxy file (proxy.ts in Next.js 16, middleware.ts before it) that protects everything will redirect the CLI's POST to a sign-in page. Stripe treats a redirect as a failed delivery, so exclude the webhook path from the matcher; the signature check is the route's authentication. Empty handlers: in development, log loudly when a handler cannot find the user an event refers to, instead of returning quietly.

Troubleshooting: when it fails loudly

Stripe's troubleshooting guide names the wrong endpoint secret as the most common cause of signature errors, and a modified request body as the next thing to check. Print the first few characters of the secret your code is using and compare them with what the CLI printed before you change anything else.

Stripe CLI webhook testing vs production: what changes?

The handler code does not change when you deploy. Five things around it do:

One decision is worth making before you write much handler code. Stripe's docs now recommend thin events for new integrations: the notification carries only the event type and the related object's ID, you verify it with parseEventNotification() and fetch the current object, and there is no payload version to keep aligned with your SDK. Snapshot events, used in this tutorial because they are what stripe listen forwards by default and what most existing code handles, carry the object as it was when the event fired. To develop against thin events, forward them explicitly:

stripe listen --forward-thin-to localhost:3000/api/webhooks/stripe-thin --thin-events "*"

If your handler writes to a database with a service key, remember that key skips row-level rules; our guide to Supabase RLS covers what that means, and the multi-tenant guide shows how to map a Stripe customer to the right organisation. If you route payment events into automations rather than code, the n8n webhook guide covers the same signature check there.

A working local loop is the start of billing, not the end: plans, the customer portal, tax and failed-payment handling all hang off these events. Our AI SaaS Builder program wires Stripe Checkout, Billing and webhooks into one product, after the build and before the launch.

Testing Stripe webhooks locally: FAQ