.env · security🔒 100% client-side — never leaves your browser

Stripe Webhook Secret: test generator and signature builder

Your real Stripe webhook secret (whsec_…) is created by Stripe, not by you. This Stripe webhook secret page shows where to find it, generates whsec_ test secrets for unit tests, and builds a valid Stripe-Signature header so you can call your webhook handler locally.

By Aliniyaz Mamat · last reviewed

Be the first to rate
generated locally · crypto.getRandomValues · nothing sent anywhere
Stripe test secret (whsec_)
For unit tests and local mocks only. Real secrets come from Stripe (Dashboard or stripe listen).
Secret value
.env line
STRIPE_WEBHOOK_SECRET=
GitHub webhook secret
Paste into Settings > Webhooks > Secret; GitHub signs with HMAC-SHA256 (X-Hub-Signature-256).
Secret value
.env line
GITHUB_WEBHOOK_SECRET=
Your own webhooks (hex)
64 hex characters for webhooks you send yourself, GitLab tokens or any HMAC-SHA256 scheme.
Secret value
.env line
WEBHOOK_SECRET=
Stripe-Signature header builder
Signs a test payload the way Stripe does, so you can call your webhook handler locally. The timestamp is fixed when the page loads; Stripe SDKs reject signatures older than 5 minutes, so press new timestamp before testing.
Stripe-Signature:
curl -X POST http://localhost:3000/api/stripe/webhook \
  -H 'Content-Type: application/json' \
  -H 'Stripe-Signature: ' \
  --data-binary '{
  "id": "evt_test_123",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_test_123",
      "object": "checkout.session"
    }
  }
}'

Key takeaways

  • ✓Stripe creates one signing secret per webhook endpoint: copy it from Dashboard → Developers → Webhooks → your endpoint → Signing secret.
  • ✓For local development, stripe listen prints a different, temporary whsec_ secret. Use that one in .env.local.
  • ✓The signature is HMAC-SHA256(secret, timestamp + "." + raw body) as hex, sent as Stripe-Signature: t=…,v1=…. The builder above produces exactly that and is checked against stripe-node's constructEvent.
  • ✓Stripe SDKs reject signatures older than 300 seconds by default, so refresh the timestamp before you replay a request.
  • ✓GitHub webhooks are different: there you choose the secret, so the GitHub preset is a real production value.

What it does

  • ▸whsec_ test secrets for unit tests and mocks
  • ▸Stripe-Signature header builder for any payload (Web Crypto HMAC-SHA256)
  • ▸Ready-made curl command to replay the event against localhost
  • ▸GitHub and generic HMAC webhook secrets you can use in production
  • ▸Everything runs in your browser

Privacy

Runs 100% in your browser. Your .env never touches our servers.

client-side only

When to use this tool

  • →Testing a webhook handler without the Stripe CLI, for example in a CI job
  • →Writing unit tests that need a signed Stripe event
  • →Debugging "No signatures found matching the expected signature" by comparing headers
  • →Creating the secret for a GitHub webhook or for webhooks your own app sends

Common mistakes

  • ⚠Pasting a self-generated whsec_ into production: it will never match what Stripe signs with
  • ⚠Using the CLI secret from stripe listen in production, or the Dashboard secret locally. Each endpoint has its own
  • ⚠Parsing the body as JSON before verifying: the signature covers the raw bytes, and re-serialised JSON no longer matches
  • ⚠Mixing test and live mode: each mode has separate endpoints and separate secrets

Where to find your real Stripe webhook secret

SituationWhere the secret comes fromLooks like
Production / staging endpointDashboard → Developers → Webhooks → endpoint → Signing secret → Revealwhsec_…
Local developmentoutput of stripe listen --forward-to localhost:3000/api/stripe/webhookwhsec_…
Endpoint created via APIsecret field in the response of POST /v1/webhook_endpoints (shown once)whsec_…
Unit testsany value, e.g. from the generator abovewhsec_…

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

app/api/stripe/webhook/route.ts
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)

  1. Take the current Unix timestamp t and the exact raw request body.
  2. Compute HMAC-SHA256 with the full secret string (including whsec_) as key over t + "." + body.
  3. Send the hex digest as Stripe-Signature: t=<t>,v1=<hex>.
  4. The receiver recomputes the HMAC, compares it in constant time, and checks that t is 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.

Frequently asked questions

Can I create my own Stripe webhook secret?

No. Stripe generates the signing secret for every endpoint and signs events with it. A self-generated whsec_ is only useful for tests and mocks where your own code does the signing.

Why does my webhook fail with "No signatures found matching the expected signature"?

Usually one of three things: the secret belongs to a different endpoint (CLI vs Dashboard), the body was parsed and re-serialised before verification, or test and live mode are mixed up.

Is the whsec_ prefix part of the key?

Yes. Stripe uses the complete string, prefix included, as the HMAC key. Do not strip it.

How long is a Stripe signature valid?

The SDKs accept a timestamp up to 300 seconds old by default (the tolerance parameter). Older replays are rejected to stop replay attacks.

Is the payload or secret sent to your server?

No. Secrets are generated and HMACs computed with the Web Crypto API in your browser.

Related tools

Learn more

Compare

coming soon

Get notified when env syncing launches

We're building a tiny tool to keep .env files in sync across teammates and environments. Leave your email — no spam, just a single launch ping.

We use your address only for this launch email. You can ask us to delete it at any time. Privacy policy