Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท Webhooks

Verifying Webhook Signatures

Understand the Stripe-Signature header, rebuild the HMAC check with node:crypto, defend against replays with a timestamp tolerance, and avoid the raw-body mistake.

Your webhook URL is public. Anyone who guesses it can send a fake payment_intent.succeeded and get free goods. The defence is a signature: Stripe signs every request with a secret only you and Stripe know, and your endpoint checks that signature before trusting anything in the body.

Stripe's official libraries do this for you, but you should understand the scheme. This lesson rebuilds it with the built-in node:crypto module, so it runs in the editor. The secret here is a made-up string, never a real key.

The Stripe-Signature header

Each request carries a header like this:

TEXT
Stripe-Signature: t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t is the Unix timestamp when Stripe signed the request.
  • v1 is the signature: an HMAC-SHA256 (a keyed hash) of the string "{t}.{raw body}", hex encoded, using your endpoint's signing secret (it starts with whsec_).

You recompute the HMAC from the raw bytes you received and compare. If one byte of the body differs, the result is completely different.

flowchart LR
  A["Raw body + t"] --> B["HMAC-SHA256 with whsec_ secret"]
  B --> C{"Equals v1?"}
  C -- yes --> D["Check timestamp age"]
  C -- no --> E["Reject with 400"]
  D --> F["Process event"]

Verification order: recompute, compare, then check freshness.

Computing and checking a signature

Node.js Sign and verify a payload

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Why a constant-time compare?

A normal === on strings stops at the first different character. An attacker measuring response times could, in theory, learn the correct signature one character at a time. timingSafeEqual takes the same time however many bytes match. It requires equal-length buffers, which is why the code checks the lengths first.

Why the timestamp tolerance?

A signature proves the body is genuine, but not that it is new. If an attacker records a real signed request, they could send it again later. Because t is part of the signed text, they cannot change it without breaking the signature, so you reject requests older than a few minutes. Stripe's libraries default to 300 seconds. Keep your server clock synchronized (NTP) or you will reject good events.

The raw-body mistake

This is the number one webhook bug. If your framework parses the JSON first and you then re-serialize it with JSON.stringify, spaces and key order may change, and the HMAC no longer matches. Verify against the exact bytes received.

Node.js Why re-serializing breaks the signature

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In Express use express.raw({ type: 'application/json' }) on the webhook route only. In Laravel, read $request->getContent(). In Python frameworks, read the request body bytes before decoding.

Keep one signing secret per endpoint, store it in an environment variable, and rotate it if it leaks. Never log the secret or commit it to Git.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What exactly does Stripe sign?

    The signed payload is the timestamp, a dot, then the raw body, so the timestamp cannot be changed without breaking the signature.
  2. 2. Why check the timestamp even if the signature matches?

    A recorded valid request would otherwise verify forever. The tolerance limits the replay window.
  3. 3. Your signature check always fails after adding a JSON body parser. Likely cause?

    Verification needs the exact raw bytes. Use a raw-body parser on the webhook route.
  4. 4. Why use timingSafeEqual instead of ===?

    Constant-time comparison prevents timing attacks that guess the signature byte by byte.

Summary

  • The Stripe-Signature header holds a timestamp t and an HMAC v1 of "t.body".
  • Recompute the HMAC with your whsec_ secret and compare in constant time.
  • Reject old timestamps to stop replay attacks.
  • Always verify the raw body, never a re-serialized one.

Next: Idempotent Event Handling