Signing Webhook Payloads: HMAC, Timestamps, and Replay Defense

The signed input is not the body alone. It is a deterministic concatenation of a version tag, the timestamp and the raw body, joined by a separator that cannot appear ambiguously. webhooks.fyi recommends concatenating body, timestamp and sensitive headers, and explicitly warns against adding unnecessary steps such as changing capitalization or inserting line breaks provider best practices. A version prefix gives you forward compatibility: if you later move to a new algorithm or add fields, the receiver can branch on the prefix instead of guessing.

A workable layout:

v1:1712345678:{"id":"evt_123","type":"payment.succeeded"}

Two rules make this safe. First, the separator must not be forgeable from the parts: use a character that cannot appear in a decimal timestamp, and prefix the body length if you want to eliminate all ambiguity. Second, sensitive headers (a tenant ID, a key ID) belong inside the digest if the receiver makes routing decisions from them, because an unsigned header can be swapped.

Then compute HMAC with SHA-256 and encode as hex or base64:

import hmac, hashlib, time

def sign(secret: bytes, body: bytes, ts: int) -> str:
    msg = b"v1:" + str(ts).encode() + b":" + body
    return hmac.new(secret, msg, hashlib.sha256).hexdigest()

headers = {
    "X-Signature-Version": "v1",
    "X-Timestamp": str(int(time.time())),
    "X-Signature": sign(SECRET, raw_body, int(time.time())),
}

Use one tool for the job on the receiving side rather than hand-rolling across languages. Standard Webhooks publishes the exact header names, encoding and verification algorithm, plus reference libraries in Python, JavaScript/TypeScript, Java/Kotlin, Rust and Go Standard Webhooks, the spec. If you are interoperating with a partner who follows it, adopting it removes a negotiation.

webhooks.fyi's security guidance states it plainly: do not use SHA-1 or MD5, and for HMAC use at least SHA-256 webhooks.fyi HMAC. Hookdeck's analysis lists the three factors that set the real strength of an HMAC: the hash function, the digest size, and the length and randomness of the key Hookdeck on SHA-256 verification. That last factor is the one teams neglect: a 12-character passphrase chosen by a human is the weak link even with SHA-256.

A byte-by-byte equality check on a signature leaks information through timing: the comparison returns early on the first mismatch, so an attacker who can measure response times can recover a valid signature one byte at a time. GitHub's documentation tells implementers never to use a plain == operator and to use a constant-time comparison such as crypto.timingSafeEqual or Rack's secure_compare GitHub's validation guide. The reference implementation on webhooks.fyi checks buffer lengths first and then calls crypto.timingSafeEqual webhooks.fyi HMAC.

Three details make this reliable in practice:

• Compare bytes, not strings. Convert both sides to Buffer or bytes with a known encoding before the call.
• Check length before calling the constant-time function. Some implementations throw on length mismatch, and that exception is itself an information leak if it produces a different response.
• Strip the algorithm prefix from the header before comparing, but parse it strictly. GitHub sends sha256=<hex>; a permissive parser that accepts an empty prefix invites confusion later GitHub's validation guide.

Failing closed matters as much as comparing safely. A missing signature header, an unknown version, a malformed timestamp or a body that exceeds your size limit should all produce a rejection before any business logic runs. Log the rejection with the delivery ID so you can tell a broken integration from an attack, and return a non-2xx status so the sender's retry logic does the right thing.

The timestamp is what turns a signature from "this was signed by someone with the key" into "this was signed recently." Without it, a captured request stays valid forever.

The algorithm on receipt:

1. Parse the timestamp header as a decimal integer of seconds since the Unix epoch. Reject anything that is not a clean integer.
2. Compute now - timestamp. If the result is greater than the tolerance, reject as expired.
3. Compute timestamp - now. If the result is greater than the tolerance, reject as future-dated.
4. Only then verify the signature over the canonical string that includes the timestamp.

That second direction is the one teams forget. A signature with a timestamp ten years in the future passes a naive "not older than five minutes" check, and if you cache or store the event, the attacker has effectively parked a valid request for later. webhooks.fyi's examples focus on the stale-request case, but the same tolerance should apply symmetrically replay prevention.

Choosing the window is a tradeoff you can reason about with numbers:

• Too tight (30 seconds): legitimate deliveries fail whenever either side's clock drifts, and NTP-synchronized hosts can still be tens of milliseconds to a few seconds apart after a leap event or a VM pause.
• Too wide (1 hour): a captured request remains useful for an hour, which is plenty of time for an attacker who has already seen it.
• Five minutes: Stripe's documented default for blocking replays, and the figure Svix recommends, described as old enough for clock skew and short enough that a captured request expires before it is useful Svix's webhook security guide, Devlume's reliability summary.

webhooks.fyi suggests a 3 to 5 minute window and notes that reliable timestamp validation depends on keeping the listener's clock in sync, with NTP as the fix replay prevention. Operationally: run a time daemon on every host that terminates webhooks, alert when offset exceeds about one second, and never run verification on a container host with a frozen clock after a long suspend.

A worked example makes the failure mode concrete. Suppose your tolerance is 300 seconds and a delivery arrives with timestamp T, and your server's clock is 400 seconds slow because NTP died during a migration. now - T evaluates to 100 seconds, which passes. The request looks fine. But every request now looks 400 seconds fresher than it is, so your effective replay window has widened to 700 seconds, and a request captured 690 seconds ago still passes. Clock skew does not just cause false rejections; it silently widens the window. Monitoring offset is the control.

If you need to test the logic without waiting, inject a clock:

def fresh(ts: int, now: int, tol: int = 300) -> bool:
    delta = now - ts
    return -tol <= delta <= tol

Negative deltas cover the future-dated case; a single comparison handles both directions.

A timestamp bounds how long a captured request stays useful. It does not stop an attacker from resending the same valid request many times inside that window. Duplicate deliveries are also a normal, documented property of webhooks: most providers deliver at least once, so you will see the same event twice without any attacker involved Hookdeck on idempotency, Hookdeck on webhooks at scale.

The right structure is one deduplication step that serves both purposes. Deduplicate on a stable identifier the provider sends (GitHub's X-GitHub-Delivery header is unique per delivery and is preserved on manual redelivery GitHub's best practices) or on a nonce you require the sender to include in the signed string.

The claim must be atomic. A check-then-insert leaves a race where two copies of an event both pass the "have I seen this?" check before either records it; a unique constraint or INSERT ... ON CONFLICT DO NOTHING lets the datastore arbitrate Prismatic on idempotency. A Redis SET key value NX EX ttl does the same job with less ceremony the Shopify walkthrough.

Sizing the deduplication window is where teams get it wrong. If your signature tolerance is 5 minutes but a provider retries for three days, a 1-hour TTL protects only the first hour. Prismatic's guidance is to keep the dedup window longer than the provider's retry window, because a short TTL against a long retry period leaves a gap Prismatic on idempotency. For replay defense specifically, the window only needs to cover your tolerance plus clock skew, so about 10 minutes of key retention is enough to make a replayed signature useless. For retry deduplication, you need the full retry horizon. Keep two windows if you need both.

Also consider what a replay can do even when it is detected. If processing means "set order status to paid," running it twice is harmless. If it means "increment balance by 2000," it is not. Absolute state changes are retry-safe; increments are not Prismatic on idempotency. Where you cannot avoid a relative change, gate it on the idempotency claim so the second attempt never reaches the mutation.

The secret is the whole security model. webhooks.fyi's provider guidance is to individualize secrets per listener (one secret per endpoint, not one per account), use high-entropy random values, and implement rotation with zero downtime by signing with multiple keys during the transition provider best practices. GitHub recommends a random string with high entropy and storage in a secure location your server can reach, never hardcoded and never committed GitHub's validation guide.

Rotation that actually works looks like this:

1. Generate the new secret and store it alongside the old one on both sides. The receiver accepts signatures from any active secret; the sender signs with the newest.
2. Wait at least one full retry horizon (and longer than your delivery timeout) so in-flight retries signed with the old key still verify.
3. Revoke the old secret. Confirm that no request has verified against it for a period longer than the retry horizon, typically by logging which key ID matched.

The key ID belongs in a header and inside the signed string, so it cannot be swapped to force verification against a weaker or retired key. ngrok's survey of 100 webhook providers found that only 8.5% offered zero-downtime secret rotation and only 27% provided versioning for forward compatibility ngrok's field guide. If you are building the sending side, those are cheap differentiators to beat.

For higher assurance, asymmetric signatures remove the shared-secret problem entirely: the sender signs with a private key and publishes the public key at a JWKS endpoint, so a leaked receiver configuration cannot be used to forge requests. FusionAuth's webhook signing docs describe RSA, EC and EdDSA keys with the public half exposed via /.well-known/jwks.json, plus a JWT header carrying a request_body_sha256 claim FusionAuth's signing docs. That design also makes rotation easier, since receivers can fetch the new public key rather than coordinate a secret exchange.

When the HMAC path is the right one (it usually is: lower latency, no key distribution infrastructure), an agent or service that terminates many third-party webhooks benefits from a single verification layer rather than per-integration code. That is the kind of plumbing a platform handles for you; Quanta Inference gives you one API key and one OpenAI-compatible surface for the models that process those events once they are verified (https://quantaintelligence.ai/inference).

Put this in the pull request that adds a webhook endpoint, and require each line to be true before merge.

Two more items worth adding for production: an IP allow list where the provider publishes its ranges (GitHub exposes them through its meta endpoint GitHub's best practices), and a response that returns quickly so the sender does not retry a slow handler (GitHub terminates connections that do not get a 2XX within 10 seconds GitHub's best practices). Neither replaces the signature, but together they cut noise.

If you are designing this from scratch for a product rather than integrating as a consumer, Standard Webhooks is the reference to copy: it defines headers, encoding, and the exact signing string, with libraries you can depend on instead of debugging your own canonicalization for the third time Standard Webhooks, the spec. webhooks.fyi tracks it alongside IETF HTTP Message Signatures and CloudEvents for teams that need a standard beyond webhooks standardization efforts.