What is webhook signature verification and how do HMAC webhooks work?

Webhook signature verification is how a receiver confirms that an HTTP request came from the expected sender and was not altered in transit. Most providers use HMAC webhooks: the sender and receiver share a secret, and the sender attaches a keyed hash of each message. Any team that emits webhooks or accepts them from third parties needs it. Otherwise a webhook endpoint is a public URL that will act on whatever JSON arrives.

The delivery flow works like this:

  1. The sender serializes the payload once and keeps the exact bytes.
  2. It builds a signing string from a timestamp, a delimiter and that raw body.
  3. It computes an HMAC, usually HMAC-SHA256, over the signing string using the shared secret.
  4. It sends the timestamp and the signature in headers. The signature value carries a scheme label such as v1=, so the algorithm can change later without breaking parsers.
  5. The receiver reads the raw body before any JSON parsing, rebuilds the same signing string, recomputes the HMAC and compares the two values in constant time.

The signature covers the raw bytes because re-serialized JSON rarely matches byte for byte. Whitespace, key order and number formatting all drift. The timestamp is included so that it cannot be changed without invalidating the signature.

A valid signature proves authenticity (someone holding the secret produced the message) and integrity (the body and timestamp are unchanged). It does not provide confidentiality, because the payload is still readable. It also does not provide authorization: the event can be genuine yet reference a resource this tenant should not touch. HTTPS is still required to encrypt the payload and keep it private in transit.

+---------------------------- SENDER ----------------------------+
|  payload --> serialize once --> raw body bytes (kept exact)    |
|                                        |                       |
|  timestamp t ------------> signing string: t + '.' + body      |
|                                        |                       |
|  shared secret ----------> HMAC-SHA256(secret, string)         |
|                                        |                       |
|                                        v                       |
|  timestamp header: t   signature header: v1=<hex>              |
+----------------------------------------+-----------------------+
                                         |
   HTTPS POST (TLS keeps payload private)|
                                         |
+----------------------------------------v-----------------------+
|  RECEIVER: read raw body bytes BEFORE any JSON parsing         |
|                                        |                       |
|  rebuild t + '.' + body --> HMAC-SHA256(same secret)           |
|                                        |                       |
|                                        v                       |
|  constant-time compare(expected, received v1= value)           |
|            |                                     |             |
|          match                                mismatch         |
|            v                                     v             |
|  authentic + unaltered                   reject request        |
|  still check authorization,              log the failure       |
|  then parse JSON and act                                       |
+----------------------------------------------------------------+

The sender signs a timestamp plus the exact raw body with HMAC-SHA256 under a shared secret, and the receiver recomputes and constant-time compares that HMAC over HTTPS, which proves authenticity and integrity but not confidentiality or authorization.

Why doesn't a valid HMAC stop replayed or duplicated deliveries?

A signature proves the bytes came from someone holding the secret. It says nothing about when they were sent or how many times. An attacker who captures one signed request (from a misconfigured proxy log, a compromised intermediary, or a debugging dump) can resend it unchanged, and the HMAC still verifies. Separately, at-least-once delivery means the sender will retry whenever it doesn't see a timely 2xx, so your endpoint receives honest duplicates even with no attacker involved.

The first defense is a timestamp that is part of the signed content, for example by signing timestamp + "." + body. A timestamp sent only in its own header proves nothing, because an attacker can rewrite it to the current time and the signature still matches. Once the timestamp is signed, the receiver rejects requests older than a tolerance window, typically a few minutes. A tighter window shrinks the replay opportunity but rejects legitimate requests delayed by clock skew or sender-side queueing.

The second layer is deduplication on a sender-assigned event ID. You must keep each processed ID for at least the tolerance window plus the sender's full retry horizon. That requires shared state across all receiver instances, such as a database unique constraint or a cache entry with a TTL. If the TTL expires before the last retry arrives, that late duplicate is processed a second time.

Threat Stopped by signed timestamp Stopped by event-ID dedup
Replay after the window closes Yes Yes, if the ID is still retained
Replay within the window No Yes
Honest retry from the sender No Yes
Edited timestamp header Yes, because the signature fails Not applicable

How do you implement webhook signature verification on the receiver?

Order matters here. Each step depends on the one before it, and doing them out of sequence is the most common source of false rejections.

  1. Capture the raw body bytes before anything parses them. The sender signed exact bytes. If you parse JSON and re-serialize it, key order, whitespace, Unicode escaping and number formatting can all change. The re-serialized body produces a different MAC even though the data is identical. Configure your framework to expose the unparsed body on the webhook route only.
  2. Parse the signature header, including its scheme prefix. A value such as v1=<hex> tells you which algorithm and key version to use. Reject unknown schemes explicitly. Never fall back to a weaker one.
  3. Check the timestamp against your tolerance window before doing any cryptographic work. Stale requests are cheap to discard.
  4. Recompute the HMAC over the timestamp and raw body, then compare it in constant time. Use your standard library's constant-time comparison function. Ordinary string equality returns as soon as it finds a mismatched byte, and that timing difference can leak how much of a forged signature was correct.
  5. Deduplicate on the event ID using a store with a retention period at least as long as the sender's retry horizon.
  6. Enqueue the event durably and return a 2xx.

When verification fails intermittently, suspect the path between the sender and your handler before you suspect the key. Global body-parsing middleware, decompression, charset normalization, request-logging filters and reverse proxies that rewrite bodies can all alter the bytes silently. These failures are hard to debug because the logged payload looks correct. To find the culprit, log a hash of the bytes the handler actually received and compare it against a body you signed yourself.

import hashlib, hmac, json, logging, time

SECRET = b"whsec_placeholder_not_a_real_secret"  # load from a secret store in practice
TOLERANCE_SECONDS = 300
seen_event_ids = set()  # stand-in: use a durable store with TTL >= sender's retry horizon

def handle_webhook(raw_body: bytes, sig_header: str, enqueue) -> int:
    # 1. raw_body must be the unparsed request bytes, not re-serialized JSON.
    # 2. Parse "t=<unix>,v1=<hex>". Only v1 is accepted; never fall back to another scheme.
    parts = dict(p.split("=", 1) for p in sig_header.split(",") if "=" in p)
    if "t" not in parts or "v1" not in parts:
        return 400
    try:
        ts = int(parts["t"])
    except ValueError:
        return 400
    # 3. Discard stale or future-dated requests before doing any crypto.
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return 400
    # 4. Recompute the MAC over timestamp + "." + exact bytes, compare in constant time.
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), parts["v1"].encode()):
        # Log a hash of the bytes actually received to compare with the sender's view.
        logging.warning("bad signature, body sha256=%s", hashlib.sha256(raw_body).hexdigest())
        return 401
    # Parse only after the bytes are authenticated.
    event = json.loads(raw_body)
    # 5. Deduplicate on event ID; a repeat delivery is acknowledged, not reprocessed.
    if event["id"] in seen_event_ids:
        return 200
    # 6. Enqueue durably first, then record the ID and acknowledge.
    enqueue(raw_body)
    seen_event_ids.add(event["id"])
    return 202

A standard-library Python receiver that follows the verification order: it uses the raw bytes, parses the versioned header, checks the timestamp, compares the HMAC in constant time, deduplicates on event ID and enqueues before returning a 2xx.

How should the receiver acknowledge and process webhooks?

The receiver's contract is narrow: return a 2xx only after the signature has been verified and the event has been durably enqueued, whether to a message queue, an outbox table, or a log. If verification fails, return a 4xx. If the enqueue fails, return a 5xx so the sender retries. Never return 2xx before the event is safely stored. A crash between acknowledgment and persistence loses the event, and the sender has no reason to send it again.

Do the actual work, such as provisioning, emailing, or updating balances, in a separate worker. This keeps response times well inside the sender's timeout, so slow downstream calls don't trigger spurious retries. The trade-off is that responsibility shifts to you. Once you acknowledge an event, the sender considers it delivered. Your workers then need their own retry policy, a dead-letter destination, and alerting on queue depth and failure rates. Otherwise a failed job disappears without anyone noticing.

Treat duplicates as normal traffic. Key processing on the event ID and record processed IDs in the same transaction as the side effect. That way a redelivered event becomes a no-op instead of a second charge.

Don't assume events arrive in order. A retried updated event can land after a later deleted. Compare each event's timestamp or sequence number with the last one you applied, and discard anything older. For sensitive state such as payment status, entitlements, or permissions, treat the webhook as a notification only. Fetch the current resource from the source API and act on that response, not on the payload.

-- PostgreSQL. Run by the worker, not the HTTP handler.
CREATE TABLE processed_events (
  event_id     text PRIMARY KEY,           -- sender's unique event ID
  processed_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE subscriptions (
  id            text PRIMARY KEY,
  status        text NOT NULL,
  last_event_at timestamptz NOT NULL       -- timestamp of the last event applied
);

-- One transaction per event. The dedup record and the side effect
-- commit together or not at all.
BEGIN;

WITH claimed AS (
  -- Inserts nothing (and returns no row) if this event was already processed.
  INSERT INTO processed_events (event_id)
  VALUES ('evt_01HXAMPLE')
  ON CONFLICT (event_id) DO NOTHING
  RETURNING event_id
)
UPDATE subscriptions
   -- Status comes from a fresh GET to the source API, not the webhook payload.
   SET status        = 'canceled',
       last_event_at = '2026-11-13T10:00:05Z'
 WHERE id = 'sub_456'
   AND EXISTS (SELECT 1 FROM claimed)              -- skip duplicates
   AND last_event_at < '2026-11-13T10:00:05Z';     -- skip stale, out-of-order events

COMMIT;

A worker-side PostgreSQL transaction that records the event ID and applies the state change atomically, turning redelivered events into no-ops and ignoring events older than the last one applied.

How should senders design webhook retries and dead-lettering?

Treat every delivery attempt as an outcome to classify. Decide up front which 4xx codes are permanent. Otherwise a misconfigured endpoint will either be retried forever or dropped silently.

Response Sender action Why
Connection error, timeout Retry with backoff The receiver may never have seen the request
5xx Retry with backoff Server-side fault, often transient
429, 408 Retry, honouring Retry-After if present The receiver is asking you to slow down
400, 404, 410, 422 Stop and dead-letter. Consider disabling on 410 The same payload will fail the same way
401, 403 Stop, dead-letter, alert the endpoint owner Usually a secret or config problem that retries won't fix
2xx Done The receiver has accepted responsibility

Compute each delay as a random value between zero and min(cap, base × 2^attempt). The jitter spreads out retries from many failed deliveries so they don't all hit a recovering receiver at the same moment. Bound both the attempt count and the total duration. Illustrative estimate: with a 30-second base, a one-hour cap and 8 attempts, the maximum delays are 30s, 1m, 2m, 4m, 8m, 16m, 32m and 60m, which gives a worst-case horizon of about two hours.

The two bounds pull against each other. Short, aggressive retries add load to a receiver that is already failing. Long horizons let a broken endpoint go unnoticed for hours. Alert on sustained failure rates instead of waiting for retries to run out.

Move exhausted deliveries to a dead-letter store that keeps the original event ID and payload, and expose a redelivery API. The receiver's dedupe TTL must exceed the retry horizon plus a safety margin. Manual redelivery can arrive much later than that, so make processing idempotent instead of relying on the TTL alone.

import random

# Illustrative values only; tune per system.
BASE_S = 30
CAP_S = 3600
MAX_RETRIES = 8
MAX_HORIZON_S = 3 * 3600  # hard stop on total retry duration

PERMANENT = {400, 404, 410, 422}
AUTH = {401, 403}

def classify(status):
    """status is None for connection errors and timeouts."""
    if status is None or status >= 500 or status in (408, 429):
        return "retry"
    if 200 <= status < 300:
        return "done"
    if status in AUTH:
        return "dead_letter_and_alert"  # secret/config problem
    # Explicit decision: PERMANENT and any other unlisted status are final.
    return "dead_letter"

def next_delay(retry_index, retry_after=None):
    # Full jitter: uniform in [0, min(cap, base * 2^n)].
    delay = random.uniform(0, min(CAP_S, BASE_S * 2 ** retry_index))
    # Honour a numeric Retry-After as a floor (HTTP-date form not handled here).
    if retry_after and retry_after.isdigit():
        delay = max(delay, int(retry_after))
    return delay

def plan(retry_index, elapsed_s, status, retry_after=None):
    """Return (action, delay_seconds) for a failed or completed attempt."""
    action = classify(status)
    if action != "retry":
        return action, None
    if retry_index >= MAX_RETRIES:
        return "dead_letter", None  # attempt budget exhausted
    delay = next_delay(retry_index, retry_after)
    if elapsed_s + delay > MAX_HORIZON_S:
        return "dead_letter", None  # duration budget exhausted
    return "retry", delay

A sender-side retry planner that classifies each response, computes full-jitter exponential backoff with an optional Retry-After floor, and dead-letters once either the attempt or total-duration budget is spent (all values are an illustrative estimate).

How do you rotate webhook signing secrets without downtime?

A signing secret that never changes turns every leak into a permanent compromise. This includes leaks through logs, a former employee's laptop, or a misconfigured CI variable. Rotation limits how long a leaked secret stays useful. Rotation only works if neither side has to switch at the same moment, because senders and receivers deploy on different schedules.

The fix is an overlap window during which two secrets are valid. The sender generates a new secret and starts signing with it. During the overlap it also does one of two things:

  • Sends multiple signatures in the signature header, one per active secret. The receiver accepts the request if any of them matches.
  • Sends a key identifier alongside a single signature. The receiver looks up that key directly instead of guessing.

Multiple signatures are simpler for receivers that don't track key IDs. Key identifiers scale better when a tenant has several keys or algorithms.

On the receiver, verification becomes a loop:

  1. Load every candidate secret that is currently active.
  2. Compute the expected HMAC over the raw body and timestamp for each secret.
  3. Compare each expected value against each provided signature using a constant-time comparison.
  4. Accept on the first match. Reject only after every candidate has failed.

Don't use an early-exit string equality check inside the loop. The loop changes how many comparisons run, but each individual comparison must still be timing-safe.

The cost is an extra code path that needs its own tests, especially for the case where only the old key matches. The bigger risk is operational. Once receivers confirm they have switched, revoke the old secret on a schedule. An overlap window left open indefinitely means you still have two live secrets, and the old one is the one most likely to have leaked.

When should you avoid shared-secret HMAC, and what are the alternatives?

HMAC is the right default for most server-to-server integrations. It needs one shared secret and a hash function that every language's standard library provides. It also verifies quickly. Its limits come from that symmetry. Because sender and receiver hold the same key, a valid signature proves only that one of the two parties produced the message. A receiver could forge an event, so the signature cannot settle a dispute over who sent what. This matters for payment events, audit trails, or any platform where receivers must not be able to fabricate deliveries.

HMAC also fails wherever byte-exact transport is not guaranteed. A proxy that re-serializes JSON, normalizes line endings or changes encoding breaks verification, even when the content means the same thing.

The alternatives trade these weaknesses differently:

  • Asymmetric signatures (such as Ed25519 or RSA): the sender signs with a private key, and receivers verify with a published public key. This provides non-repudiation, but the scheme is just as byte-sensitive as HMAC.
  • Mutual TLS authenticates the connection, not the message. Once TLS terminates at a load balancer, the payload carries no proof of origin.
  • Thin payloads carry only an event ID and type. The receiver fetches current state from the API using its own credentials. This costs an extra request per event but makes the payload itself low-value.
Approach Non-repudiation Key management burden Verification complexity Tolerance of payload modification
Shared-secret HMAC No Low: one secret per endpoint Low None
Asymmetric signatures Yes Moderate: protect private key, publish public keys Moderate None
Mutual TLS Per connection only High: issue, renew and revoke certificates Handled by the TLS stack Not applicable after termination
Thin payload + fetch Not needed Uses existing API credentials Low High

How does this design affect development cost and save engineering time?

The full design has real costs, and most of them are operational rather than code:

  • Dedupe storage. Its TTL must outlast the sender's retry window, and it becomes a dependency. If it is unavailable, you must choose between rejecting deliveries and relying on retries, or processing without dedupe and accepting duplicates.
  • Retry scheduler. It must be durable and survive restarts.
  • Dead-letter tooling. It needs a replay action and someone who actually watches the queue.
  • Dual-secret support for rotation.
  • Verification on the raw body. This must run before any parsing middleware, which is a code path that breaks quietly when the framework stack changes.

Each item is small, but each needs tests and an owner.

The design prevents failures that are expensive because they are hard to reconstruct afterwards. Examples include a customer charged twice because a retry was processed twice, signature failures that start only after someone adds body-parsing middleware, events lost while an endpoint returned errors that nobody saw, and an emergency secret change that breaks every integration at once.

Illustrative estimate (assumed numbers, not a benchmark): Break-even (years) = build hours ÷ (incident hours avoided per year − maintenance hours per year). Assume 80 build hours, 4 avoided incidents a year at 16 hours each (64 hours), and 16 maintenance hours a year. That gives 80 ÷ (64 − 16) ≈ 1.7 years. The estimate excludes refunds, cleanup of wrongly provisioned resources and lost customer trust.

Build the full design from day one when webhooks move money, provision resources or change state that is costly to reverse. If the receiver treats each webhook as a hint and re-fetches current state from the API, a lighter version is acceptable: verify the signature, use a simple timestamp window and a few retries, and skip dedupe storage and dead-letter tooling.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to webhook signature verification, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.