Signing and Verifying Geofence Webhook Payloads

A geofence trigger delivered by webhook is an assertion with consequences: it starts a billing period, releases a payment, opens a barrier, or files a compliance record. An unsigned webhook is an assertion anyone who learns the URL can make, and webhook URLs leak constantly — into logs, into screenshots, into third-party integrations. This page sits under webhook fan-out and retry budgets within Event Routing & Backpressure, and it covers the signature scheme, the replay window it needs, and the interaction with the retry machinery that makes a naive implementation reject its own legitimate retries.

Concept and specification #

The signature is an HMAC over a canonical string that binds the payload to a moment and to a specific delivery:

$$\sigma =\text{HMAC-SHA256}(k_{\text{tenant}},;\text{ts}\parallel \text{“.”}\parallel \text{body})$$

Three properties follow from the construction. Including the timestamp inside the MAC input means it cannot be altered without invalidating the signature, which is what makes a replay window enforceable. Using the raw body bytes rather than a re-serialised structure means the receiver verifies exactly what it will parse, closing the class of attacks where signer and verifier disagree about JSON canonicalisation. And a per-tenant key means a compromised key affects one subscription.

The replay window is where most implementations get the trade-off wrong in one direction or the other. Too narrow and legitimate deliveries fail: a retry sequence with a 30 s cap plus queueing can deliver a payload three minutes after it was signed. Too wide and a captured request stays useful for hours. The resolution is that the window does not have to do the whole job alone — the receiver already holds an idempotency key for duplicate suppression, and a replayed request presents a key the receiver has seen, so it is suppressed as a duplicate regardless of the window. A 300 s window plus a 24 h idempotency store is materially stronger than either alone and comfortably accommodates the retry sequence.

Step-by-step implementation #

1. Sign once, per delivery, over the exact bytes to be sent.

from __future__ import annotations
import hashlib, hmac, time

SCHEME = "v1"

def sign(secret: bytes, body: bytes, ts: int | None = None) -> tuple[str, str]:
    t = str(ts if ts is not None else int(time.time()))
    mac = hmac.new(secret, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return t, f"{SCHEME}={mac}"

2. Re-sign on every retry attempt, not once per trigger. This is the detail that breaks naive implementations: a signature computed when the trigger was created carries a timestamp that ages through the retry sequence, so the fourth attempt presents a timestamp four minutes old and the receiver’s window rejects it. Re-signing costs 4.1 µs and keeps the timestamp fresh. The idempotency key stays constant across attempts — it identifies the logical trigger — while the signature and timestamp identify the attempt.

3. Verify in constant time, and check the timestamp before the MAC. The order matters for cost, not for security: rejecting a stale timestamp is a comparison, and computing a MAC over a large body is not, so checking cheaply first avoids a CPU amplification vector.

def verify(secret: bytes, body: bytes, ts_header: str, sig_header: str,
           window_s: int = 300, now: int | None = None) -> bool:
    try:
        ts = int(ts_header)
    except (TypeError, ValueError):
        return False
    t = now if now is not None else int(time.time())
    if abs(t - ts) > window_s:
        return False                       # cheap check first
    scheme, _, mac = sig_header.partition("=")
    if scheme != SCHEME:
        return False
    expected = hmac.new(secret, f"{ts}.".encode() + body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, mac)   # constant time

4. Support two active keys during rotation. Publish both key ids, accept either, and give tenants a window to move. Rotation without overlap requires a simultaneous cutover on both sides, which no tenant can coordinate and which therefore never happens — so the keys never rotate, which is the actual security failure.

5. Bind the signature to more than the body if the URL is meaningful. Where the same tenant has several subscriptions with different destinations, include the subscription id in the canonical string; otherwise a payload signed for one destination can be replayed to another. This is the webhook equivalent of an audience claim.

6. Publish a verification snippet, not just a specification. Most receiver-side failures are canonicalisation mistakes — verifying a re-serialised body, decoding the hex before comparing, comparing with ==. A five-line snippet in the two or three languages tenants actually use removes more integration incidents than any amount of documentation.

Benchmark and verification #

Measured over 10 million deliveries with 4 KB payloads:

HMAC is the right default at this cost profile: it is thirteen times cheaper to sign and thirty-three times cheaper to verify than Ed25519, and both parties already share a secret because the subscription was configured through an authenticated channel. Asymmetric signatures earn their cost only when the receiver must prove provenance to a third party — a regulator, an auditor, a downstream partner — because an HMAC can be forged by anyone who could have verified it, which makes it useless as evidence.

The bottom row is the recommended configuration and its overhead is 148 bytes on a 4 KB payload, or 3.6%. At 1M deliveries/sec that is 148 MB/s of additional egress, which is worth noticing but not worth trading for the absence of authentication.

Verify a deployment by attempting the attacks. Replay a captured request inside the window and confirm the receiver suppresses it as a duplicate; replay it outside the window and confirm rejection; alter one byte of the body and confirm the MAC fails; present a valid signature for subscription A to subscription B’s endpoint and confirm rejection if the subscription id is bound. Each is a few lines in an integration test and each has failed in production somewhere.

Failure modes and edge cases #

The first row is worth restating because it is subtle and produces a failure that looks like an intermittent network problem. Sign at the moment of the HTTP request, inside the retry loop, so the timestamp reflects the attempt rather than the trigger. If the architecture forces signing earlier — a pre-rendered payload cached across attempts, as the memory optimisation in the parent topic suggests — then the timestamp and signature must be recomputed per attempt while the cached body is reused, which the construction above supports because the body is an input rather than being modified.

One more interaction is worth naming. The signature covers the body, so any per-attempt content — an attempt counter in the payload, a “delivered at” field — invalidates the reuse of a cached body and forces re-serialisation per attempt, undoing the allocation win. Put per-attempt metadata in headers, outside the signed body, and the body stays a shared immutable object across the whole fan-out.

Related #

• Webhook Fan-Out & Retry Budgets — the parent topic, whose shared-payload optimisation this scheme has to respect.
• Exponential Backoff with Jitter for Trigger Webhooks — the retry timing the replay window has to accommodate.
• Deduplicating ENTER/EXIT Events with Idempotency Keys — the key that completes the replay defence.