Agents

What is a webhook signature — and why without one your bot believes any lie

Illustration: two identical envelopes on a desk, one with a wax seal, one without

You've wired up payments. The payment service hits your /webhook endpoint, you read the body, see "payment succeeded" — and unlock access for the user. Works.

Now the uncomfortable thought: that address isn't known only to the payment service. It sits in dashboard settings, it's shown up in logs, it may have landed in a screenshot or a chat with an AI. And anyone who has seen it can send the exact same request saying "payment succeeded." Your code can't tell the difference.

A webhook signature is what makes that difference visible.

A webhook URL is not a password

The beginner reflex is to make the URL longer and weirder: /webhook-x7f2k9. That's not protection, it's an illusion. The address travels through too many places to count as a secret, and it never changes.

The problem runs deeper: an ordinary webhook is just an HTTP request from outside. Nothing about it proves the sender. Headers are forgeable, and a "from" field in the body can say anything.

So you need a way to check not where it came from but whether the sender knew a shared secret.

How the signature works

The mechanics are simple and rather elegant.

When you set up the webhook, the service shows you a string like whsec_a1b2c3... — the endpoint secret. Only two parties have it: the service and you. It never travels over the network.

Then, on every request:

  1. The service takes the request body and attaches a timestamp.
  2. It runs that through a hash function together with the secret. Out comes a short fingerprint — an HMAC.
  3. It puts the fingerprint and timestamp in a header (with Stripe it's Stripe-Signature).

On your side you do exactly the same with your copy of the secret — and compare fingerprints. Match? The body is untouched and the sender knew the secret. No match? Reply 400 and do nothing.

The key property: the fingerprint is computed from the content. Swap 1 for 100,000 in the body and the fingerprint changes — and forging it without the secret isn't possible.

In practice it's one line; the service's library does the work:

const event = stripe.webhooks.constructEvent(rawBody, signatureHeader, endpointSecret);

The big trap: parsed JSON breaks the signature

Almost everyone stumbles here, and the failure looks absurd: right code, right secret, signature "doesn't match."

The reason is the word raw. The fingerprint is computed over the body byte for byte as the service sent it. But a typical server setup parses JSON into an object first thing. When you later stringify that object back, you get a different string: whitespace moved, key order may differ, escaping differs. Same meaning — different bytes. The fingerprint won't match.

So for the webhook route you have to turn off automatic body parsing:

// correct — the body arrives raw
app.post('/webhook', express.raw({ type: 'application/json' }), handler);

// broken — the body is already parsed, the signature won't match
app.post('/webhook', express.json(), handler);

You can parse the JSON yourself — but after verifying the signature, not before.

The timestamp: replay protection

A signature alone isn't enough. Imagine an attacker captures one genuine "payment succeeded" request — whole, signature included. That signature is valid. They can send it to you again and again, granting themselves access forever. That's a replay attack.

That's exactly why a timestamp goes into the signed string: it can't be altered without breaking the signature. Your side checks the request is recent — libraries accept roughly a five-minute drift by default. Sometimes people set that tolerance to zero to "remove the extra check," which actually disables the recency check entirely. Don't.

The other half of the defence is on you: store the ID of each processed event and silently ignore repeats. That's useful even without attackers — services genuinely retry delivery when you answered with an error or took too long.

What if the service has no signature?

It happens — there's no single standard, everyone does their own thing. You'll meet three variants.

A fingerprint signature, as above: GitHub puts it in X-Hub-Signature-256, Stripe in Stripe-Signature. The most reliable option.

A shared token. The service simply sends an agreed string in a header — that's how Telegram webhooks work, for instance. Weaker than a signature: the token travels the network on every request, and anyone who intercepts it can forge messages. Still incomparably better than nothing. One detail that matters: compare such a token not with a plain === but with a constant-time comparison function — ordinary comparison bails on the first mismatched character, so response timing can in theory leak the secret character by character. Your standard library has a function for this.

Nothing at all. Then your only defence is to distrust the request body entirely. Got a "payment succeeded"? Don't believe the letter: call the service's API and ask it yourself what happened to that payment. In this mode a webhook is just a "go check" nudge, not a source of truth. Worth doing even when a signature exists, if money is involved.

And common to all three: only accept webhooks over HTTPS. Over plain HTTP both the token and the body are visible to anyone in transit.

Can't I just check the sender's IP?

You can, but it's a weak substitute. Service IP ranges change, cloud and proxy setups make one IP shared by thousands of customers, and an IP in headers is easier to spoof than you'd think. A signature proves knowledge of a secret — that's stronger. IP filtering is fine as an extra layer, never as the only one.

What if the signature doesn't match?

Check in this order, top down:

  1. The body is parsed before verification — by far the most common cause; fix it with a raw body.
  2. Wrong secret. Test and live endpoints have different secrets, and a local debugging tunnel issues a third one.
  3. Something rewrote the body in transit — a proxy or framework "tidied" the encoding.

If the request never arrives at all, that's a different story — covered in why your webhook isn't firing.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →