Stripe Webhook Signature Verifier

Why webhook signature verification matters

Stripe webhooks are public HTTP POST requests sent from Stripe's servers to an endpoint on your app. The endpoint URL is discoverable from your account or from a leaked log, which means anyone on the internet can send a forged payload claiming a charge succeeded. Signature verification with your webhook secret proves three things at once: the payload came from Stripe, the body bytes have not been altered in transit, and the request was issued recently (within the timestamp tolerance you allow).

The verification rules are documented by Stripe and identical across SDKs: extract the t= and v1= parts from the Stripe-Signature header, compute HMAC-SHA256(secret, '{t}.{raw_body}'), compare it to v1 in constant time, and reject events whose timestamp is older than 300 seconds. This tool runs the same algorithm in your browser so you can debug a failing verification without rotating secrets or shipping log statements to production.

How does the verification work?

1. 1. Parse the header. Split the Stripe-Signature value on commas, then extract t= and v1=. Older v0 schemes are not used in production.
2. 2. Compute HMAC-SHA256. The signed string is the timestamp, a literal dot, and the exact raw body bytes Stripe sent. The browser's Web Crypto API runs the HMAC with your whsec_ secret as the key.
3. 3. Compare in constant time. The computed signature is compared to v1 byte by byte. Returning false on the first mismatch would leak timing information, so the comparison runs in O(n) regardless of where the difference is.
4. 4. Check timestamp age. Even with a valid signature, events older than the tolerance (300 seconds by default) are rejected to prevent replay attacks.

Frequently Asked Questions

What does the Stripe webhook signature verifier do?

The Stripe Webhook Signature Verifier checks whether a Stripe-Signature header matches the HMAC-SHA256 you would compute server-side with your webhook secret. Paste the raw request body, the signature header, and your whsec_ secret. The tool runs HMAC verification in your browser, returns pass or fail, and decodes the event JSON so you can see what Stripe sent.

Why is webhook signature verification required?

Stripe webhooks are public HTTP POST requests sent from Stripe to a URL on your app. Anyone who learns that URL can send a forged payload claiming a payment succeeded. Signature verification with your webhook secret proves the request actually came from Stripe and that the body bytes have not been altered. Without it, your endpoint is an unauthenticated mutation surface anyone can call.

What is in the Stripe-Signature header?

The header is a comma-separated list of key-value pairs. The two that matter are t= (the Unix timestamp Stripe signed) and v1= (the HMAC-SHA256 signature in hex). The signed string is {timestamp}.{raw_body}. Stripe documents older v0 schemes you should ignore. Always verify against v1 and use the exact raw bytes Stripe sent, not a re-serialized version of the JSON.

Why does my real webhook signature fail to verify even when the secret is right?

The most common cause is that your framework parsed the request body before you computed the signature. JSON.parse plus JSON.stringify produces a different byte string than what Stripe signed (different whitespace, key order, escaping). You must verify against the exact raw bytes. In Next.js Route Handlers, read await request.text() once and use the same string for both verification and parsing.

Is my webhook secret sent anywhere?

No. The verification runs entirely in your browser using the Web Crypto API. Your webhook secret, payload, and signature header never leave your machine. There is no backend, no logging, and no analytics on the inputs. You can paste a production secret to debug a failing webhook without rotating it afterward.

What is the timestamp tolerance and why does it matter?

Stripe recommends rejecting webhooks whose t= timestamp is more than 300 seconds (5 minutes) old. This blocks replay attacks where someone captures a valid webhook and replays it later. The verifier shows the timestamp age so you can see if a verification failure is a tolerance issue or a true signature mismatch. Stripe SDKs default to 300 seconds; raise it only with a clear reason.