# Webhook signature: definition, how HMAC verification works and what breaks it

Source: https://leverprice.com/glossary/webhook-signature
Updated: 2026-11-17

> A webhook signature is a code the sender computes from the request body and a shared secret, usually with HMAC-SHA256, and sends in a header. The receiver recomputes it from the raw body; if the two match, the event came from the provider and nobody changed it. A signed timestamp also lets the receiver reject replayed events.

A webhook signature proves that an event really came from your payment provider and that nobody changed it on the way. When Stripe tells your server a checkout completed, it sends a `Stripe-Signature` header with a timestamp and an HMAC-SHA256 of the timestamp plus the raw body, keyed with your endpoint's `whsec_` secret ([Stripe](https://docs.stripe.com/webhooks)).

## How it works

The provider and your server share a secret. For each event the provider signs a defined string, and your server repeats the calculation:

1. Read the raw request body, before any JSON parsing.
2. Build the signed string exactly as the provider defines it.
3. Compute HMAC-SHA256 with the signing secret.
4. Compare your result with the header in constant time.
5. Reject the event if its timestamp is too old. Stripe's libraries default to a 5-minute tolerance.

| Provider | Signature header | What is signed |
|---|---|---|
| [Stripe](https://docs.stripe.com/webhooks) | `Stripe-Signature` (`t=…,v1=…`) | `{t}.{raw body}` |
| [Polar](https://polar.sh/docs/integrate/webhooks/delivery) | `webhook-signature`, with `webhook-id` and `webhook-timestamp` | `{id}.{timestamp}.{body}` ([Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)) |
| [Dodo Payments](https://docs.dodopayments.com/developer-resources/webhooks) | `webhook-signature` (`v1,<base64>`), with the same two headers | `{id}.{timestamp}.{body}` |
| [Lemon Squeezy](https://docs.lemonsqueezy.com/help/webhooks/signing-requests) | `X-Signature` | the raw body only |

Lemon Squeezy's signature has no timestamp, so replay protection is up to you: record the order IDs you have already processed and skip repeats. Lemon Squeezy also stops processing transactions on March 31, 2027, so plan the move to another provider's scheme ([Lemon Squeezy migration](https://docs.lemonsqueezy.com/migration)).

A minimal Stripe check looks like this. In production, prefer the provider's library, such as `stripe.webhooks.constructEvent` in Stripe's Node SDK.

```ts title="verify-stripe-signature.ts"
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyStripeSignature(
  rawBody: string,
  header: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  const pairs = header.split(",").map((part) => part.split("=", 2));
  const timestamp = pairs.find(([key]) => key === "t")?.[1];
  const signatures = pairs.filter(([key]) => key === "v1").map(([, value]) => value ?? "");
  if (!timestamp || signatures.length === 0) return false;

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > toleranceSeconds) return false;

  const expected = Buffer.from(createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"));
  return signatures.some((signature) => {
    const received = Buffer.from(signature);
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
```

## Why it matters for pricing

Revenue numbers in a price test are only as good as the events behind them. An endpoint that skips the check accepts any POST that looks like a payment, so a single fake event can make a losing price look like the winner.

This is why Leverprice asks for your webhook signing secret: a signing secret can confirm events but cannot move money, and revenue that does not arrive in a verified provider event is labeled unverified ([verified revenue](https://leverprice.com/blog/verified-revenue-webhooks)).

## Common mistakes

- Verifying a parsed and re-serialized body. Frameworks that parse JSON first change the bytes, so read the raw body, for example with `await request.text()` in a fetch-style handler.
- Comparing signatures with `===`, which can leak timing information. Use a constant-time comparison.
- Skipping the timestamp check, which lets an attacker replay an old, validly signed event.
- Mixing test-mode and live-mode secrets, which makes every live event fail verification.

## Related terms

Verified purchases are what make [revenue per visitor](https://leverprice.com/glossary/revenue-per-visitor) trustworthy in a [price test](https://leverprice.com/glossary/price-testing). Polar, Lemon Squeezy and Dodo Payments each act as a [merchant of record](https://leverprice.com/glossary/merchant-of-record) and sign their webhooks too, and [payment processing fees](https://leverprice.com/glossary/payment-processing-fees) are what the provider keeps from each verified payment.

## Frequently asked questions

### Is a webhook signing secret the same as an API key?

No. An API key can call the provider's API, including refunds and payouts, while a signing secret can only prove that an event is genuine.

### What should my endpoint do when verification fails?

Return an error status and log the attempt without processing the event. Stripe retries live-mode deliveries for up to three days, so a genuine event that failed because of a bug can still arrive after you fix it ([Stripe](https://docs.stripe.com/webhooks)).

### Why does my signature check fail even with the right secret?

Most often the body was parsed before you verified it, or a proxy changed it. Verify against the exact bytes the provider sent, and check that you are using the secret for the right endpoint and mode.
