Verifying Stripe webhook signatures: Stripe-Signature, timestamp tolerance and secret rotation

What it is

Stripe's webhook guide documents the Stripe-Signature header and its constructEvent() verification helper, which takes the raw request body, the header value and the endpoint secret (prefixed whsec_). The header carries a t= timestamp and one or more signatures, each prefixed by a scheme; "currently, the only valid live signature scheme is v1", and test events also carry a fake v0 signature that must be ignored. Because the timestamp "is part of the signed payload, it's also verified by the signature", and "our libraries have a default tolerance of 5 minutes between the timestamp and the current time." The signed string is the timestamp, a ., and the raw body; the HMAC key is the endpoint secret exactly as shown, whsec_ prefix included. Stripe's troubleshooting page shows the failure text: Webhook signature verification failed. Err: No signatures found matching the expected signature for payload.

Why it matters

The tolerance window defeats replay of a captured, valid payload. Stripe's troubleshooting page names the wrong endpoint secret as the most common cause of the failure above (a stripe listen CLI secret and a Dashboard endpoint secret both start with whsec_ but differ); the next is a modified body (see the raw-body trap article), because any framework that reformats the JSON before your handler sees it changes the bytes Stripe signed. When you roll a secret and delay the old one's expiration (up to 24 hours), "Stripe generates one signature per secret until expiration", so the header temporarily contains more than one v1= value — a receiver must accept a match against any of them.

How to apply

• Read the raw, unparsed body on the webhook route.
• Split Stripe-Signature on commas, read t= as the timestamp and collect every v1= value.
• Recompute HMAC-SHA256 of "{t}.{raw_body}" with the endpoint secret and compare against each v1 value with a constant-time function; accept on any match.
• Reject if the timestamp is older than the tolerance (300 seconds unless intentionally widened); use NTP rather than raising the tolerance, and never pass 0, which "disables the recency check entirely". The snippet also rejects future timestamps, stricter than the libraries.
• During a delayed rotation, deploy the new whsec_ secret before the old one expires; either one matches while both are active.

import hmac, hashlib, time

def verify_stripe(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    ts, sigs = None, []
    for item in header.split(","):
        key, _, value = item.strip().partition("=")
        if key == "t" and value.isdecimal():
            ts = value
        elif key == "v1":                        # ignore v0 and unknown schemes
            sigs.append(value.encode())
    if ts is None or not sigs or abs(time.time() - int(ts)) > tolerance:
        return False
    signed = ts.encode() + b"." + raw_body       # exact bytes Stripe signed
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    return any(hmac.compare_digest(expected, s) for s in sigs)

Pitfalls

Mounting an app-wide express.json() ahead of the webhook route; Stripe's troubleshooting page says to place app.use(express.json()) after it. Raising the tolerance instead of fixing clock skew. Parsing the header into a dict, which keeps only one v1 value and rejects valid deliveries during rotation. Base64-decoding the secret the way Standard Webhooks does; Stripe's libraries use the full string as the key.