Paste the Stripe webhook error.
Get the fix.

No signatures found matching the expected signature

StripeSignatureVerificationError: No signatures found matching the expected signature for payload. Are you passing the raw request body you received from Stripe?

The signature is computed over the exact bytes Stripe sent. If your code parses the body as JSON and stringifies it again, or anything changes whitespace or encoding, the HMAC no longer matches. If the body is untouched, the secret is wrong (see the next entry).

usually because

• –Calling req.json() and then JSON.stringify() before constructEvent
• –A wrapper, logger or middleware that reads and re-serialises the body
• –The right body but the wrong whsec_ secret

fix

1. 1.In an App Router route handler, read the body once with await req.text()
2. 2.Pass that string, the stripe-signature header and STRIPE_WEBHOOK_SECRET to constructEvent
3. 3.Only JSON-parse after verification (event is already parsed for you)
4. 4.If it still fails, check which whsec_ secret is in use

// src/app/api/stripe/webhook/route.tsimport Stripe from "stripe"; +added: export const runtime = "nodejs";+added:  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); export async function POST(req: Request) {  const sig = req.headers.get("stripe-signature");−removed:   const payload = await req.json();+added:   if (!sig) return new Response("Missing signature", { status: 400 });+added:   const body = await req.text(); // raw body: never req.json()  let event: Stripe.Event;  try {−removed:     event = stripe.webhooks.constructEvent(JSON.stringify(payload), sig!, process.env.STRIPE_WEBHOOK_SECRET!);+added:     event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);  } catch (err) {    return new Response(`Invalid signature: ${(err as Error).message}`, { status: 400 });  }  // ...handle event.type...  return Response.json({ received: true });}

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed

Wrong webhook secret (CLI vs Dashboard, test vs live)

No signatures found matching the expected signature for payload  (works locally with stripe listen, fails in production)

Every endpoint has its own signing secret. The secret printed by stripe listen only verifies events forwarded by the CLI. A Dashboard endpoint has a different one, and test-mode and live-mode endpoints have different ones too.

usually because

• –The stripe listen whsec_ is set in production
• –A test-mode secret is used with a live-mode endpoint (or the reverse)
• –You rolled the secret in the Dashboard and didn't redeploy
• –Extra quotes or a trailing space in the env var

fix

1. 1.Stripe Dashboard → Developers → Webhooks → your endpoint → reveal the signing secret
2. 2.Set it as STRIPE_WEBHOOK_SECRET in the production environment (the matching mode: live for live keys)
3. 3.Redeploy so the running build sees the new value
4. 4.Keep the stripe listen secret only in .env.local

# local only: printed by `stripe listen`
STRIPE_WEBHOOK_SECRET=whsec_from_stripe_listen

# production (set on your host, not in git):
# STRIPE_WEBHOOK_SECRET=whsec_from_dashboard_endpoint

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed
$ stripe events resend evt_... --webhook-endpoint=we_...
# then the deployed endpoint; add --live for a live-mode event

307 / 308 / 301 redirect

Webhook delivery failed: HTTP status code 308 (Permanent Redirect)

Stripe does not follow redirects. Any 3xx counts as a failed delivery. Next.js and hosts redirect apex to www (or the reverse), http to https, and add or strip trailing slashes.

usually because

• –Endpoint registered as https://example.com but the site redirects to https://www.example.com
• –trailingSlash: true in next.config adds a slash and redirects
• –http:// instead of https://
• –A locale or auth redirect in proxy.ts / middleware.ts

fix

1. 1.Run curl -i -X POST https://your-url/api/stripe/webhook and look at the status and Location header
2. 2.Update the Dashboard endpoint to the final URL from Location, exactly
3. 3.Exclude /api/stripe/webhook from locale and auth redirects

curl -i -X POST https://example.com/api/stripe/webhook
# HTTP/2 308
# location: https://www.example.com/api/stripe/webhook   <- register THIS url

# A healthy endpoint answers 400 (missing signature), not 3xx/401/404.

$ curl -i -X POST https://<your-domain>/api/stripe/webhook
# expect 400 (missing signature) from your handler, not 3xx, 401, 403, 404 or 405
$ stripe events resend evt_... --webhook-endpoint=we_...
# we_... is the endpoint id in the Dashboard; add --live for a live-mode event

401 / 403 from auth middleware or Vercel Deployment Protection

Webhook delivery failed: HTTP status code 401 (Unauthorized)

Something answered before your handler ran. Stripe has no session cookie, so auth middleware rejects it or redirects it to sign-in. On Vercel, Deployment Protection (Vercel Authentication) blocks preview deployments, and sometimes production, with a 401.

usually because

• –proxy.ts / middleware.ts protects /api/* and the matcher doesn't exclude the webhook
• –Vercel Deployment Protection is on for the URL Stripe calls (often a preview URL)
• –Cloudflare / WAF bot protection challenges Stripe's requests
• –Basic auth on a staging site

fix

1. 1.Exclude /api/stripe/webhook from the middleware matcher: the Stripe signature is its authentication
2. 2.Point Stripe at your production domain, not a *.vercel.app preview URL
3. 3.Or turn off Deployment Protection for that URL, or use Vercel's Protection Bypass for Automation
4. 4.Allow Stripe's webhook IPs through your WAF if needed

export const config = {−removed:   // run everywhere except static files−removed:   matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],+added:   // run everywhere except static files and the Stripe webhook+added:   matcher: ["/((?!api/stripe/webhook|_next/static|_next/image|favicon.ico).*)"],};

$ curl -i -X POST https://<your-domain>/api/stripe/webhook
# expect 400 (missing signature) from your handler, not 3xx, 401, 403, 404 or 405
$ stripe events resend evt_... --webhook-endpoint=we_...
# we_... is the endpoint id in the Dashboard; add --live for a live-mode event

404 Not Found (wrong path)

Webhook delivery failed: HTTP status code 404 (Not Found)

Nothing answers at the URL Stripe calls. In the App Router, the URL comes from the folder path of route.ts, and only exported HTTP method names are handlers.

usually because

• –Endpoint is /api/webhooks/stripe but the file is app/api/stripe/webhook/route.ts
• –The file is named webhook.ts or page.tsx instead of route.ts
• –The handler isn't exported as POST (e.g. export default)
• –A typo, or a missing /api prefix, or a basePath

fix

1. 1.Map the URL to the file: /api/stripe/webhook → src/app/api/stripe/webhook/route.ts
2. 2.Export a named function: export async function POST(req: Request)
3. 3.Test with curl -i -X POST: you should get 400 (missing signature), not 404

$ curl -i -X POST https://<your-domain>/api/stripe/webhook
# expect 400 (missing signature) from your handler, not 3xx, 401, 403, 404 or 405
$ stripe events resend evt_... --webhook-endpoint=we_...
# we_... is the endpoint id in the Dashboard; add --live for a live-mode event

Timed out / not returning 2xx fast

Webhook delivery failed: Timed out connecting to remote host

Stripe expects a 2xx quickly. If your handler sends emails, calls other APIs or waits on a cold database before answering, the request can time out (around 10 seconds or more counts as a failure) and Stripe retries it, which also causes duplicates.

usually because

• –Sending email or calling third-party APIs inside the handler
• –Cold start plus a slow database connection
• –Serverless function timeout on your host
• –Awaiting work that isn't needed to acknowledge the event

fix

1. 1.Verify the signature, do the minimal DB write, return 200
2. 2.Move slow work to a queue or background job (or after() in Next.js)
3. 3.Keep the handler idempotent because retries will come

−removed: await recordEvent(event);−removed: await sendReceiptEmail(event); // Stripe waits for this−removed: await syncToCrm(event);         // ...and this+added: import { after } from "next/server";+added:  +added: await recordEvent(event);            // fast, idempotent DB write+added: after(() => sendReceiptEmail(event)); // runs after the responsereturn Response.json({ received: true });

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed

Duplicate events / missing idempotency

Same checkout.session.completed processed twice: two welcome emails, credits granted twice

Stripe delivers at least once. Retries after a timeout or non-2xx, and occasionally plain duplicates, mean the same event.id can arrive more than once. Handlers that increment, insert or send emails without checking will repeat the side effect.

usually because

• –No record of which event.id values were already processed
• –Incrementing credits or inserting rows instead of writing current state
• –A slow handler that Stripe retried

fix

1. 1.Store event.id with a unique constraint before doing side effects; skip if it already exists
2. 2.Prefer writing the current state (status = X) over increments or toggles
3. 3.Return 200 for duplicates so Stripe stops retrying

model StripeEvent {  id        String   @id // evt_...  createdAt DateTime @default(now())} // in the handler, after constructEvent:−removed: await db.user.update({−removed:   where: { id: userId },−removed:   data: { credits: { increment: 100 } }, // runs again on every retry−removed: });+added: try {+added:   await db.stripeEvent.create({ data: { id: event.id } });+added: } catch {+added:   return Response.json({ received: true, duplicate: true });+added: }

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed
$ stripe events resend evt_...   # the evt_ id stripe listen printed
$ stripe events resend evt_...   # same id again

Out-of-order events

customer.subscription.updated (active) arrived after customer.subscription.deleted, user got Pro back

Stripe doesn't guarantee delivery order. A retried older event can land after a newer one, so writing event.data.object blindly can overwrite fresh state with stale state.

usually because

• –Writing the event payload snapshot straight to the database
• –Assuming created always arrives before updated
• –Retries of an old event

fix

1. 1.Take only the object id from the event
2. 2.Re-fetch the subscription with stripe.subscriptions.retrieve(id) and write its current state
3. 3.Or compare event.created / a stored timestamp and ignore older events

case "customer.subscription.updated":case "customer.subscription.deleted": {−removed:   const sub = event.data.object; // may be an old, late-retried snapshot+added:   const sub = await stripe.subscriptions.retrieve(event.data.object.id);  await db.user.updateMany({    where: { stripeCustomerId: sub.customer as string },    data: { subscriptionStatus: sub.status },  });  break;}

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger customer.subscription.updated
$ stripe events resend evt_...   # the customer.subscription.created event from that run

Edge runtime / crypto errors

SubtleCryptoProvider cannot be used in a synchronous context. Use `await constructEventAsync(...)` instead of `constructEvent(...)`

constructEvent is synchronous and uses Node's crypto. On the Edge runtime or Cloudflare Workers only Web Crypto exists, which is async.

usually because

• –export const runtime = "edge" on the webhook route
• –Deploying to Cloudflare Workers / Pages
• –A bundler polyfill that breaks node:crypto

fix

1. 1.Simplest: export const runtime = "nodejs" on the webhook route
2. 2.On Edge/Workers: await stripe.webhooks.constructEventAsync(body, sig, secret, undefined, Stripe.createSubtleCryptoProvider())
3. 3.Still read the body with await req.text()

−removed: export const runtime = "edge";−removed:  −removed: const event = stripe.webhooks.constructEvent(+added: const event = await stripe.webhooks.constructEventAsync(  await req.text(),  sig,  process.env.STRIPE_WEBHOOK_SECRET!,+added:   undefined,+added:   Stripe.createSubtleCryptoProvider(),);

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed

Missing raw body / body already used

TypeError: Body is unusable: Body has already been read  ·  Webhook payload must be provided as a string or a Buffer

The request body stream can be read once. If something read it already, or you pass an object instead of the raw string, verification can't run. The Pages Router bodyParser: false config does nothing in App Router route handlers.

usually because

• –Reading req.json() for logging, then req.text() for verification
• –Copying a Pages Router example (export const config = { api: { bodyParser: false } }, micro's buffer())
• –Passing a parsed object to constructEvent

fix

1. 1.Read once: const body = await req.text()
2. 2.Delete Pages Router body config and the micro dependency from App Router routes
3. 3.If you need to log, log after verification using the event object

// src/app/api/stripe/webhook/route.tsimport Stripe from "stripe"; −removed: // Pages Router config: ignored by App Router route handlers−removed: export const config = { api: { bodyParser: false } };+added: export const runtime = "nodejs"; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); export async function POST(req: Request) {  const sig = req.headers.get("stripe-signature");−removed:   console.log("webhook", await req.json()); // body is now used up−removed:   const body = await req.text(); // throws: Body is unusable+added:   if (!sig) return new Response("Missing signature", { status: 400 });+added:   const body = await req.text(); // raw body: never req.json()  let event: Stripe.Event;  try {−removed:     event = stripe.webhooks.constructEvent(body, sig!, process.env.STRIPE_WEBHOOK_SECRET!);+added:     event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);  } catch (err) {    return new Response(`Invalid signature: ${(err as Error).message}`, { status: 400 });  }  // ...handle event.type...  return Response.json({ received: true });}

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed

Events not enabled on the endpoint (nothing arrives)

Payment succeeded in Stripe but my webhook never fired / no deliveries listed for the endpoint

A Dashboard endpoint only receives the event types you selected, in the mode (test or live) where you created it. Stripe CLI forwarding doesn't reach production.

usually because

• –checkout.session.completed or customer.subscription.* not selected
• –The endpoint was created in test mode but the payment was live (or the reverse)
• –Endpoint disabled after repeated failures
• –Listening on a connected account instead of your account

fix

1. 1.Dashboard → Developers → Webhooks → endpoint → check the event list and mode
2. 2.For subscriptions add checkout.session.completed and customer.subscription.created/updated/deleted
3. 3.Use 'Send test event' or stripe trigger checkout.session.completed to confirm delivery

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger invoice.payment_failed
# test-mode Dashboard endpoints receive triggered events too

stripe listen forwarding problems (local)

[ERROR] Failed to POST: Post "http://localhost:3000/api/webhook": dial tcp [::1]:3000: connect: connection refused

The CLI receives events and forwards them to a local URL. It fails if the dev server isn't running, the port or path is wrong, or your app uses a different secret than the one stripe listen printed.

usually because

• –next dev isn't running, or runs on another port
• –Wrong path in --forward-to
• –localhost resolves to IPv6 ::1 while the server listens on IPv4
• –STRIPE_WEBHOOK_SECRET is the Dashboard secret, not the CLI one

fix

1. 1.Start next dev first, then stripe listen --forward-to localhost:3000/api/stripe/webhook
2. 2.Copy the whsec_ it prints into .env.local and restart next dev
3. 3.Try 127.0.0.1 instead of localhost if you see [::1] connection refused
4. 4.Fire a test with stripe trigger checkout.session.completed

npm run dev
stripe listen --forward-to localhost:3000/api/stripe/webhook
# copy the printed whsec_... into .env.local, restart dev
stripe trigger checkout.session.completed

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
$ stripe listen --print-secret   # the whsec_ to put in .env.local
$ stripe trigger checkout.session.completed

Timestamp outside the tolerance zone

StripeSignatureVerificationError: Timestamp outside the tolerance zone

The stripe-signature header carries a timestamp, and the library rejects events older than the tolerance (300 seconds by default) to stop replay attacks. Either your server clock is off, or you're replaying an old saved payload.

usually because

• –Server or container clock drift (no NTP)
• –Replaying a saved request from a fixture or log
• –Queueing the raw request and verifying it minutes later

fix

1. 1.Sync the server clock (NTP) and check date -u against real UTC
2. 2.Verify the signature as soon as the request arrives, then queue the parsed event
3. 3.For tests, generate fresh headers with stripe.webhooks.generateTestHeaderString instead of old ones

$ date -u   # should match real UTC
$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed

Can't map the event to a user (missing metadata / customer id)

Webhook returns 200 but the user is still on Free / updateMany count: 0 / Cannot read properties of undefined (reading 'userId')

The webhook ran but couldn't tell which of your users the event belongs to. Subscription events carry a customer id, not your user id, so you need a stored stripeCustomerId or metadata set when the Checkout Session was created.

usually because

• –Checkout Session created without client_reference_id or metadata.userId
• –stripeCustomerId never saved on the user
• –A new Customer created per checkout (customer_email) instead of reusing one
• –Reading metadata from the subscription when you only set it on the session

fix

1. 1.Create Checkout with client_reference_id: user.id (and subscription_data.metadata.userId if you need it on the subscription)
2. 2.On checkout.session.completed save session.customer as the user's stripeCustomerId
3. 3.Look up later subscription events by stripeCustomerId; pass customer for returning users

await stripe.checkout.sessions.create({  mode: "subscription",  line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }],+added:   client_reference_id: user.id,+added:   subscription_data: { metadata: { userId: user.id } },+added:   ...(user.stripeCustomerId ? { customer: user.stripeCustomerId } : { customer_email: user.email }),  success_url: `${origin}/billing?success=1`,  cancel_url: `${origin}/billing`,});

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed --add checkout_session:client_reference_id=<test-user-id>
# the fixture is a one-time payment; also run one subscription checkout in test mode

Static export can't run API routes

Error: export const dynamic = "force-static"/ output: export ... route /api/stripe/webhook cannot be exported  ·  405 Method Not Allowed

With output: "export" Next.js produces only static files. A POST route handler that verifies signatures needs a server or a function runtime, so on a static host the webhook either fails the build or returns 404/405.

usually because

• –output: "export" in next.config
• –Hosting on a static-only host (GitHub Pages, plain S3, a Pages project with no functions)

fix

1. 1.Remove output: "export" and deploy to a host that runs Next.js (Vercel, Node, Docker, OpenNext on Cloudflare)
2. 2.Or keep the site static and run the webhook as a separate function / Worker
3. 3.Then register that function's URL in Stripe

$ curl -i -X POST https://<your-domain>/api/stripe/webhook
# expect 400 (missing signature) from your handler, not 3xx, 401, 403, 404 or 405
$ stripe events resend evt_... --webhook-endpoint=we_...
# we_... is the endpoint id in the Dashboard; add --live for a live-mode event