Anyone can fake a Stripe “payment succeeded”. Verify your webhook

What a webhook is, and why anyone can POST to it

When someone pays you through Stripe Checkout, Stripe tells your server about it by sending an HTTPS POST with a JSON event to a URL you registered, your webhook endpoint. A typical one looks like https://your-app.com/api/webhook. Your code reads the event, sees checkout.session.completed, and gives the customer what they paid for.

Stripe’s own docs say webhooks are how you should fulfil orders: the customer’s browser might never make it back to your success page, and subscriptions and delayed payment methods change state long after checkout.

The catch: the door is open to the whole street

Stripe requires your endpoint to be a publicly accessible HTTPS URL. That’s the point: Stripe’s servers have to reach it. But so can everyone else. The endpoint has no idea who’s knocking unless it checks.

• A URL isn’t a password. Paths like /api/webhook, /api/stripe/webhook and /webhooks/stripe are what every tutorial and AI assistant uses, so they’re easy to guess. They also show up in public repos, logs and browser bundles.
• The payload is just JSON. Anyone can type {"type":"checkout.session.completed", …}. Event IDs, session IDs and amounts in the body prove nothing on their own.
• Stripe gives you the proof. Every event Stripe sends carries a signature in the Stripe-Signature header, made with a secret only you and Stripe know. That header is the doorman’s ID check.

THE BUILDER’S TAKEAWAYYour webhook is the one door in your app that grants paid access. It has to check ID like it means it.

• Stripe Docs: receive Stripe events in your webhook endpoint
• Stripe Docs: verify events are sent from Stripe
• Stripe Docs: fulfill orders (Checkout)

How a fake “payment succeeded” gets someone Pro

This is how it happens. There’s no famous named heist here, because a forged webhook doesn’t look like an attack in your logs. It looks like a sale. Here is the kind of handler the episode is about, next to the fixed version:

// app/api/webhook/route.js
export async function POST(req) {
  const event = await req.json();   // whatever anyone sent

  // It kept saying "No signatures found matching
  // the expected signature", so…
  // const sig = req.headers.get('stripe-signature');
  // event = stripe.webhooks.constructEvent(body, sig, secret);

  if (event.type === 'checkout.session.completed') {
    const email = event.data.object.customer_email;
    await db.users.update({ email }, { plan: 'pro' });
  }
  return Response.json({ received: true });
}

// app/api/webhook/route.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const secret = process.env.STRIPE_WEBHOOK_SECRET!; // whsec_…

export async function POST(req: Request) {
  const body = await req.text();   // raw, untouched
  const sig = req.headers.get('stripe-signature') ?? '';

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, secret);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  // Only now is this really Stripe talking.
  await handle(event);
  return Response.json({ received: true });
}

On the left, the handler trusts whatever arrives. An attacker who knows (or guesses) the URL sends one request with their own email in customer_email, and the database marks them Pro. Then their cousin does it. Then a guy who wrote STRIPE on his shirt. No card, no Stripe, no record in your Stripe Dashboard, just a new “customer” in your app.

Test your own endpoint in ten seconds

Send your own endpoint a forged event with no signature. This is the same kind of request the attacker would send, and it’s the fastest way to know where you stand:

# Send YOUR OWN endpoint a forged event, with no Stripe-Signature header.
curl -i -X POST https://your-app.com/api/webhook \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_fake_1","object":"event","type":"checkout.session.completed",
       "data":{"object":{"id":"cs_fake_1","object":"checkout.session",
       "payment_status":"paid","customer_email":"you+test@example.com"}}}'

# Verified handler:   HTTP/1.1 400   (and nobody gets Pro)
# Unverified handler: HTTP/1.1 200   (check your database. Did you just upgrade a stranger?)

// ❌ Every one of these can be typed by the user.
if (localStorage.getItem('isPaid') === 'true') showProFeatures();
if (new URLSearchParams(location.search).get('paid') === '1') unlockPro();
await fetch('/api/upgrade', { method: 'POST', body: JSON.stringify({ plan: 'pro' }) });

// ✅ The server decides, from its own database, which only a verified webhook writes to.
const { plan } = await fetch('/api/me').then((r) => r.json());

THE BUILDER’S TAKEAWAYIf a request can grant Pro, assume someone other than Stripe will send it.

• Stripe Docs: verify events are sent from Stripe
• Stripe Docs: fulfill orders (Checkout)

Is this rare? One scan says no

In May 2026, the security vendor securityscanner.dev reported that it probed about 6,000 web apps and found 1,542 that accepted forged Stripe webhook events. According to the vendor, it sent minimal fake checkout.session.completed events, with no Stripe-Signature header, to 17 common webhook paths per host, and counted any 200, 201 or 202 reply as accepted.

• Treat it as a vendor claim. It’s one company’s scan, not an independent study, and a 2xx reply doesn’t prove an app actually granted anything. It does prove the handler didn’t reject an unsigned request, which a verified handler always does.
• The pattern they describe is the one in the episode. Signature verification sits on a TODO list, or got commented out while fighting the error, and the handler ships without it. The vendor also says code generators often produce handlers without the check unless you ask.
• It’s spread across hosts. The vendor counted about 720 on custom domains, 198 on Render and 142 on Vercel, among others.

The exact number matters less than the shape: it takes one unauthenticated request to find out, so assume someone will try yours.

THE BUILDER’S TAKEAWAYWebhook paths are predictable and the test is one request. Scanners do it at scale.

• securityscanner.dev (vendor claim): “We probed 6,000 web apps for Stripe webhook signature checks. 1,542 don’t bother.” (May 2026)

Verify the signature with constructEvent

Stripe signs every event it sends. The official libraries check it for you in one call. In Node, that’s stripe.webhooks.constructEvent() with three things:

If the signature matches and the timestamp is recent, it returns the parsed Stripe.Event. If anything is wrong, it throws a StripeSignatureVerificationError. Catch it, return 400, and do nothing else.

What the signature actually is

The header looks like t=1492774577,v1=5257a8…,v0=6ffbb5… (on one line). Stripe computes an HMAC with SHA-256, using your endpoint secret as the key, over the string timestamp + "." + raw body. constructEvent recomputes it and compares. An attacker without your whsec_ can’t produce a matching v1, and changing even one byte of the body or the timestamp breaks it.

• Only v1 counts. Stripe sends an extra fake v0 signature on test events; ignore every scheme except v1 to prevent downgrade attacks. The library already does.
• Don’t hand-roll it unless you must. If you do, use a constant-time comparison and check the timestamp yourself. Stripe documents the manual steps, but recommends the official libraries.
• whsec_ is not sk_. The signing secret verifies incoming events. Your secret API key calls Stripe. Both stay on the server, and neither goes in client code.

THE BUILDER’S TAKEAWAYOne function call is the difference between a doorman and an open door.

• Stripe Docs: verify events are sent from Stripe
• stripe-node README: webhook signing

The raw-body trap (and the exact code per framework)

This is why the check “kept failing” in the episode. The signature covers the exact bytes Stripe sent. Most frameworks helpfully parse JSON before your code runs. If you then hand constructEvent the parsed object, or JSON.stringify it back into a string, the bytes are different (whitespace, key order, escaping, number formatting) and verification fails, even though the data “looks” the same.

Stripe’s docs: any manipulation to the raw body of the request causes the verification to fail. So the rule is: read the raw body first, verify, then use event.data.object, which the library has already parsed for you.

Next.js App Router

// app/api/webhook/route.ts  (Next.js App Router)
import Stripe from 'stripe';

export const runtime = 'nodejs'; // the default; on 'edge', use constructEventAsync

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  // Read the body ONCE, as text. Don't call req.json() before this.
  const body = await req.text();
  const sig = req.headers.get('stripe-signature') ?? '';

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch (err) {
    console.warn('Stripe webhook rejected:', (err as Error).message);
    return new Response('Invalid signature', { status: 400 });
  }

  // event.data.object is already parsed for you. No JSON.parse needed.
  return Response.json({ received: true });
}

Next.js Pages Router

// pages/api/webhook.ts  (Next.js Pages Router)
import type { NextApiRequest, NextApiResponse } from 'next';
import Stripe from 'stripe';

// Turn off Next's body parser for THIS route, so the raw bytes survive.
export const config = { api: { bodyParser: false } };

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

async function rawBody(req: NextApiRequest): Promise<Buffer> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
  return Buffer.concat(chunks);
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    res.setHeader('Allow', 'POST');
    return res.status(405).end('Method Not Allowed');
  }
  const body = await rawBody(req);
  const sig = req.headers['stripe-signature'] as string;

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${(err as Error).message}`);
  }

  // …handle event…
  res.status(200).json({ received: true });
}

Express

// server.js  (Express)
import express from 'express';
import Stripe from 'stripe';

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

// 1. The webhook route comes FIRST, with a raw parser on this route only.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    // req.body is a Buffer here, exactly the bytes Stripe signed.
    event = stripe.webhooks.constructEvent(
      req.body,
      req.headers['stripe-signature'],
      process.env.STRIPE_WEBHOOK_SECRET,
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // …handle event…
  res.json({ received: true });
});

// 2. JSON parsing for every OTHER route goes AFTER the webhook route.
app.use(express.json());
app.post('/api/other', (req, res) => { /* … */ });

app.listen(3000);

Hono, Cloudflare Workers, Deno, Bun and edge runtimes

// src/index.ts  (Hono on Cloudflare Workers, Bun or Deno)
import { Hono } from 'hono';
import Stripe from 'stripe';

type Env = { STRIPE_SECRET_KEY: string; STRIPE_WEBHOOK_SECRET: string };
const app = new Hono<{ Bindings: Env }>();

app.post('/webhook', async (c) => {
  const stripe = new Stripe(c.env.STRIPE_SECRET_KEY);
  const body = await c.req.text();                 // raw body
  const sig = c.req.header('stripe-signature') ?? '';

  try {
    // Web Crypto is async, so use the async variant outside Node.
    const event = await stripe.webhooks.constructEventAsync(
      body, sig, c.env.STRIPE_WEBHOOK_SECRET,
      undefined, Stripe.createSubtleCryptoProvider(),
    );
    // …handle event…
    return c.json({ received: true });
  } catch (err) {
    return c.text(`Webhook Error: ${(err as Error).message}`, 400);
  }
});

export default app;

THE BUILDER’S TAKEAWAYVerify the bytes Stripe sent, not your framework’s opinion of them.

• Stripe Docs: resolve webhook signature verification errors
• stripe-node: webhook-signing examples (Express, Next.js App and Pages Router, Deno)
• stripe-node README: webhook signing

“No signatures found matching the expected signature for payload”

This is the message that got the check commented out. Stripe’s troubleshooting page puts it simply: if you see it, at least one of the three arguments you passed to constructEvent() is wrong. Here’s every message stripe-node can throw, and what each one means:

The wrong-secret checklist

Stripe calls the wrong endpoint secret the most common error. Every one of these is a different whsec_:

• Stripe CLI vs Dashboard. stripe listen prints its own secret (it stays the same between restarts). A Dashboard or API endpoint has a different one. Don’t verify CLI-forwarded events with the Dashboard secret, or the other way around.
• Sandbox vs live. If the same URL is registered for test and live, Stripe says the secret is different for each.
• Each endpoint. Several endpoints means several secrets. Use the one for the endpoint that’s calling you.
• Whitespace. A newline or space pasted into the env var breaks the match. Newer stripe-node versions add a note to the error when the secret contains whitespace.
• Rolled secrets. After Roll secret in Workbench, the old one keeps working for up to 24 hours if you chose a delay, then stops. Update your env var in that window.

Timestamp tolerance and replays

A replay attack resends a real, validly signed event that someone captured. Because the timestamp is inside the signed payload, it can’t be changed without breaking the signature, so constructEvent rejects events older than its tolerance: 300 seconds by default in stripe-node. Stripe generates a fresh timestamp and signature for every delivery attempt, so its own retries still pass.

THE BUILDER’S TAKEAWAYThe error isn’t the bug. It’s the doorman telling you the package was opened.

• Stripe Docs: resolve webhook signature verification errors
• Stripe Docs: verify events are sent from Stripe
• Stripe CLI reference: stripe listen
• stripe-node README: webhook signing

Handle each event once, and only fulfil verified, paid events

A verified event is real, but it can still arrive twice, out of order, or for a payment that hasn’t cleared. Stripe’s docs say webhook endpoints might occasionally receive the same event more than once, that delivery order isn’t guaranteed, and that in live mode failed deliveries are retried for up to three days with exponential back-off (three times over a few hours in a sandbox).

1. Record every event ID under a unique key

-- One row per Stripe event you have handled.
create table stripe_events (
  id           text primary key,          -- evt_…
  type         text not null,
  processed_at timestamptz not null default now()
);

-- And one fulfilment per Checkout Session, even if two events point at it.
alter table purchases add constraint purchases_session_unique unique (checkout_session_id);

Stripe also notes that in some cases two separate Event objects are generated for the same thing. That’s why fulfilment gets its own unique key on the object, here the Checkout Session ID, not just the event ID.

2. Fulfil from the API, in one transaction

// lib/stripe-webhook.ts  (postgres.js shown; any database with a unique key works)
import Stripe from 'stripe';
import sql from './db';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function handle(event: Stripe.Event) {
  // Only the events you subscribed to. Ignore the rest.
  if (event.type !== 'checkout.session.completed' &&
      event.type !== 'checkout.session.async_payment_succeeded') return;

  // Re-fetch from Stripe: the API is the source of truth, not the payload.
  const session = await stripe.checkout.sessions.retrieve(
    event.data.object.id, { expand: ['line_items'] },
  );
  if (session.payment_status === 'unpaid') return; // delayed method: wait for async_payment_succeeded

  // Who paid? The user ID YOU put on the session when you created it, server-side.
  const userId = session.client_reference_id;
  if (!userId) throw new Error(`No client_reference_id on ${session.id}`);

  await sql.begin(async (tx) => {
    // Seen this event before? Then do nothing.
    const fresh = await tx`
      insert into stripe_events (id, type) values (${event.id}, ${event.type})
      on conflict (id) do nothing returning id`;
    if (fresh.length === 0) return;

    // Same transaction: the event is marked done only if the upgrade happens.
    await tx`
      insert into purchases (checkout_session_id, user_id)
      values (${session.id}, ${userId})
      on conflict (checkout_session_id) do nothing`;
    await tx`update users set plan = 'pro' where id = ${userId}`;
  });
}

Three details carry the security here:

• Re-fetch the object. Stripe’s fulfilment guide retrieves the Checkout Session from the API (with line_items expanded) and checks payment_status before fulfilling. It’s also a second, independent proof the session is real.
• Check payment_status. unpaid means don’t fulfil yet. Delayed methods like bank debits send checkout.session.async_payment_succeeded later.
• Identify the user from your own data. Set client_reference_id (or metadata) when your server creates the session, from your auth session. Don’t look users up by an email someone typed.

// When you create the Checkout Session (server-side), attach YOUR user ID.
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: process.env.PRO_PRICE_ID!, quantity: 1 }],
  client_reference_id: user.id,              // from your auth session, not from the request body
  success_url: 'https://your-app.com/welcome?session_id={CHECKOUT_SESSION_ID}',
});

3. Listen only to the events you need

4. Return 2xx fast, do the slow work after

Stripe says your endpoint must quickly return a 2xx before any complex logic that could cause a timeout, and recommends processing events with an asynchronous queue so a burst (like the first of the month, when subscriptions renew) can’t overwhelm you. Verify, record the event, enqueue the heavy work (emails, provisioning, analytics), and respond. With a success_url set, Checkout also waits up to 10 seconds for your response to checkout.session.completed before redirecting the customer, so a slow handler shows up as a slow checkout.

THE BUILDER’S TAKEAWAYVerification proves who sent it. Idempotency and re-fetching prove it should change anything.

• Stripe Docs: webhook best practices, handle duplicate events
• Stripe Docs: receive Stripe events in your webhook endpoint
• Stripe Docs: fulfill orders (Checkout)
• Stripe Docs: using webhooks with subscriptions

Test it with the Stripe CLI before you ship

You don’t need a public URL to test signed events. The Stripe CLI forwards real, signed events from your sandbox to localhost:

# 1. Log in once
stripe login

# 2. Forward events to your local server (keep this running)
stripe listen --forward-to localhost:3000/api/webhook
# > Ready! Your webhook signing secret is whsec_…   ← put THIS in .env.local

# 3. In another terminal, fire a real, signed test event
stripe trigger checkout.session.completed

# 4. Replay a specific event to a registered endpoint (duplicate test)
stripe events resend evt_123 --webhook-endpoint=we_123

1. Run your app on localhost:3000, then stripe listen --forward-to localhost:3000/api/webhook and copy the whsec_ it prints into your local env.
2. Run stripe trigger checkout.session.completed. The stripe listen terminal should show the event and your handler’s 200.
3. Send the forged curl request from the attack section to localhost. You should get 400, and nothing in your database should change.
4. Trigger the same event twice, or use stripe events resend, and confirm the user is upgraded exactly once.
5. Deploy, register the production endpoint in Workbench with only the events you need, set that endpoint’s own whsec_ in production, and run the forged curl against production once.

Unit-test the check itself

stripe-node can sign a payload for you with a test secret, so you can prove in CI that good signatures pass and tampered or missing ones fail:

// webhook.test.ts  (sign a fake payload with a test secret, no network needed)
import Stripe from 'stripe';

const stripe = new Stripe('sk_test_dummy');
const secret = 'whsec_test_secret';
const payload = JSON.stringify({ id: 'evt_test_webhook', object: 'event' }, null, 2);

const header = stripe.webhooks.generateTestHeaderString({ payload, secret });
const event = stripe.webhooks.constructEvent(payload, header, secret);       // passes
expect(event.id).toBe('evt_test_webhook');

// Change ONE byte of the body and it must throw:
expect(() => stripe.webhooks.constructEvent(payload + ' ', header, secret)).toThrow();
// And the forged request from the attack section, with no header at all:
expect(() => stripe.webhooks.constructEvent(payload, '', secret)).toThrow();

THE BUILDER’S TAKEAWAYA test that proves a forged event gets a 400 is worth more than a handler that looks right.

• Stripe CLI reference: stripe listen
• Stripe CLI reference: stripe trigger
• Stripe Docs: receive Stripe events in your webhook endpoint
• stripe-node README: webhook signing

“Make the error go away” is not a security fix

In the episode, Claude points out that it wrote the webhook after being asked to “make the error go away”, and it’s very literal. That’s the joke, but the pattern is real: the signature error is loud, the fix looks like plumbing, and deleting one line makes everything work. For everyone.

The three moves are small: verify with constructEvent and the raw body, handle each event ID once, and only grant Pro for verified, paid events you re-fetched. Our other guides cover the same kind of gap elsewhere: Supabase Row Level Security, keeping API keys out of the browser and protecting a paid AI endpoint.

THE BUILDER’S TAKEAWAYTutorials skip it because it’s boring. Attackers love boring.