Where to find your real Stripe webhook secret
| Situation | Where the secret comes from | Looks like |
|---|---|---|
| Production / staging endpoint | Dashboard → Developers → Webhooks → endpoint → Signing secret → Reveal | whsec_… |
| Local development | output of stripe listen --forward-to localhost:3000/api/stripe/webhook | whsec_… |
| Endpoint created via API | secret field in the response of POST /v1/webhook_endpoints (shown once) | whsec_… |
| Unit tests | any value, e.g. from the generator above | whsec_… |
Store it as STRIPE_WEBHOOK_SECRET, one value per environment. Test and live mode endpoints are separate, so staging (test mode) and production (live mode) always have different secrets. The Stripe .env generator shows the full set of Stripe keys.
Verifying the signature in your handler
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
export async function POST(req: Request) {
const body = await req.text(); // raw body, NOT req.json()
const signature = req.headers.get("stripe-signature")!;
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
} catch (err) {
return new Response(`Webhook Error: ${(err as Error).message}`, { status: 400 });
}
// handle event.type …
return new Response("ok");
}In Express, mount the route with express.raw({ type: "application/json" }) before any express.json() middleware, otherwise the body is already parsed when you verify it.
How Stripe signs a webhook (and what the builder does)
- Take the current Unix timestamp
tand the exact raw request body. - Compute
HMAC-SHA256with the full secret string (includingwhsec_) as key overt + "." + body. - Send the hex digest as
Stripe-Signature: t=<t>,v1=<hex>. - The receiver recomputes the HMAC, compares it in constant time, and checks that
tis less than 300 seconds old.
Because the builder follows these steps, you can paste a body, copy the generated curl command and hit your local handler with a signature it accepts, as long as your .env.local holds the same secret. GitHub does the same with X-Hub-Signature-256: sha256=<hex> over the body alone, without a timestamp.