DEV Community

Cover image for Stripe webhook timestamp outside the tolerance zone? Fix the clock, don't set tolerance to 0
WebhookProof
WebhookProof

Posted on

Stripe webhook timestamp outside the tolerance zone? Fix the clock, don't set tolerance to 0

A webhook handler can pass every signature check and still reject the event because it looks too old. The fix people reach for first is setting the tolerance to 0, which makes the error disappear. Stripe's docs name that as a mistake.

This post covers what the timestamp in the Stripe-Signature header is for, what Stripe says about the default tolerance, what it recommends for server clocks, and why retries aren't the cause. Every claim links to the doc it comes from (see Sources at the end).

What the timestamp is for

Stripe's docs describe the threat: "A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them." To mitigate it, "Stripe includes a timestamp in the Stripe-Signature header."

That timestamp can't be edited on the way: "Because this timestamp is part of the signed payload, it's also verified by the signature, so an attacker can't change the timestamp without invalidating the signature."

So the signature proves the payload is Stripe's, and the timestamp lets the application decide whether it arrived recently enough. Per the docs: "If the signature is valid but the timestamp is too old, you can have your application reject the payload."

The default tolerance

Stripe states: "Our libraries have a default tolerance of 5 minutes between the timestamp and the current time." The docs add: "You can change this tolerance by providing an additional parameter when verifying signatures."

An error about the timestamp being outside the tolerance therefore means the gap between the signed timestamp and the current time, as the verifying code sees it, was larger than the allowed window. Two places can produce that gap: the signed timestamp is old, or the server's idea of "now" is off.

Fix the clock

Stripe's instruction: "Use Network Time Protocol (NTP) to make sure that your server's clock is accurate and synchronizes with the time on Stripe's servers."

Practical checks:

  1. Confirm the host or VM that runs the webhook handler has time synchronization turned on.
  2. Log the difference between the current time and the t= value of each incoming Stripe-Signature header. A consistent offset points to clock drift.
  3. Check where verification happens. If the raw body and header are stored and verified later, the age is measured at that later moment. Verify in the request handler, then hand work to a queue. Stripe asks the endpoint to "quickly return a successful status code (2xx) before any complex logic that could cause a timeout."
// Verify on receipt, using the default tolerance. Don't pass 0.
const event = stripe.webhooks.constructEvent(
  rawBody,
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);
// ...return 2xx now, do the slow work in a worker
Enter fullscreen mode Exit fullscreen mode

Retries are not the cause

After downtime it's tempting to blame old retried events. Stripe's docs say otherwise: "Stripe generates the timestamp and signature each time we send an event to your endpoint. If Stripe retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt."

A retried delivery carries a fresh timestamp. If retries fail with a timestamp error, the clock or a delayed verification step is the place to look.

Why a tolerance of 0 is a trap

Stripe lists it as a common mistake: "Don't use a tolerance value of 0. Using a tolerance value of 0 disables the recency check entirely."

With the recency check off, a captured payload and signature can be re-sent later and still pass. That's the replay attack the timestamp exists to stop. A very large tolerance gives much of the same exposure, so the clock is the thing to correct.

A related habit: replaying a saved payload by hand. A body and signature header copied from a log will fail once they're past the tolerance window. That's the protection working, not a bug. For testing, trigger a fresh event so Stripe signs a new timestamp.

Checklist

  • [ ] Signature verification runs in the request handler, on the raw body
  • [ ] The default tolerance is used (no 0, no huge value)
  • [ ] The server clock is synchronized with NTP
  • [ ] The offset between current time and t= is logged while debugging
  • [ ] The handler returns a 2xx before slow work
  • [ ] Hand-replayed payloads are expected to fail once they're older than the window

A rejected timestamp is one of several ways a webhook endpoint can misbehave without anyone noticing. WebhookProof's free checker sends 3 harmless test requests to a webhook URL you own and reports whether Stripe can reach it and whether unsigned requests are rejected. The full guide is here: Stripe webhook timestamp outside the tolerance zone

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-11-13.

Sources

  • Stripe, Receive Stripe events in your webhook endpoint (Preventing replay attacks, default tolerance, NTP, tolerance 0, retries and new timestamps, quickly return a 2xx response): https://docs.stripe.com/webhooks

Top comments (2)

Collapse
 
bedirhandev profile image
Bedirhan Elibol •

Agree on not setting tolerance to 0. Before widening it, compare the server clock with NTP, because a drifting host makes every event look old. Log the signed timestamp next to the server time for a few failures; if the gap is a few seconds, the clock is the bug.

Collapse
 
packetexchange_api profile image
Packet Exchange Api •

The tip to log the gap between now and the t value on every delivery is the part I would keep permanently, not only while debugging.

A steady offset points at drift, while a gap that grows with load points at verification happening after a queue or a slow body parser. Worth graphing it as a metric and alerting well before five minutes.

Did you see the offset jump after a VM suspend or snapshot restore in your testing?