Webhook Signature Verification Middleware Design Prompt
Design a webhook receiver middleware that verifies HMAC signatures, enforces timestamp tolerance, and rejects forged or replayed payloads before any automation logic runs on the request.
- Target user
- Platform engineers hardening webhook-driven automation endpoints
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior platform engineer who has watched an unauthenticated webhook endpoint get sprayed with forged payloads that triggered real automation. I will provide: - The webhook source (GitHub, Stripe, Slack, a custom sender) and its signing scheme - The signing secret rotation policy and where the secret currently lives - The runtime/framework receiving the request and the automation it triggers - Any current verification logic and observed abuse or false rejections Your job: 1. **Signature scheme** — identify the exact algorithm (HMAC-SHA256, Ed25519), the signed payload (raw body vs. parsed), and the header(s) carrying the signature and timestamp for [WEBHOOK_SOURCE]. 2. **Constant-time verification** — write middleware that recomputes the signature over the RAW request body and compares using a constant-time function, before the body is parsed or routed. 3. **Timestamp tolerance** — reject requests whose signed timestamp is outside a [TOLERANCE_WINDOW] (e.g. 5 minutes) to blunt replay, and explain the clock-skew trade-off. 4. **Replay protection** — define a short-lived seen-ID store (delivery ID or nonce) so a captured-and-replayed valid request is rejected once. 5. **Secret rotation** — support verifying against multiple active secrets during a rotation window so rotation does not drop deliveries. 6. **Failure behavior** — specify status codes and logging for forged, stale, and replayed requests, ensuring rejected requests never reach the automation handler. Output as: annotated middleware code for [RUNTIME], a header/field mapping table, and a verification test matrix covering valid, forged, stale, and replayed cases. Verify against the source's official signing docs and recorded sample deliveries in a staging receiver before enabling on the production endpoint; never trust the parsed body's signature over the raw bytes.
Why this prompt works
A webhook endpoint is an unauthenticated door into your automation unless you make it otherwise. Anyone who learns the URL can POST to it, and if the handler trusts the payload, a forged request becomes a real action — a deploy, a refund, a teardown. The prompt forces the model to treat verification as middleware that runs before parsing and routing, which is the only place it can reliably gate the request. By demanding the signature be computed over the raw body, it heads off the most common real-world bypass: re-serializing JSON shifts whitespace and key order, so a signature checked against the parsed-then-reserialized body silently fails to match what the sender actually signed.
The prompt also separates the three distinct guarantees that engineers routinely conflate. Authenticity (HMAC) proves the sender holds the secret. Freshness (timestamp tolerance) limits how long a captured request stays usable. Uniqueness (a seen-ID store) stops a valid request from being replayed inside that window. Asking for all three, plus rotation support, prevents the half-solution where someone adds an HMAC check, calls it secure, and leaves the replay door open. Rotation matters because the moment you can verify against only one secret, rotating it means dropping in-flight deliveries.
Finally, the required test matrix — valid, forged, stale, replayed — turns a vague “is it secure” into concrete cases you can assert in CI. The model drafts the middleware and tests quickly, but you verify each case against the source’s official signing documentation and real sample deliveries, because a verification bug fails open: it keeps accepting requests while quietly trusting forgeries.
Related prompts
-
Idempotency-Key Write Path Design Prompt
Design an idempotency-key scheme for an automation that makes external write calls — key derivation, store, conflict handling, and TTL — so retries, replays, and concurrent runs cannot create duplicate orders, charges, tickets, or resources.
-
Webhook Dedupe and Replay-Protection Receiver Design Prompt
Design a hardened inbound webhook receiver that verifies signatures, rejects replayed or stale deliveries, and deduplicates at-least-once redeliveries so automated downstream actions fire exactly once per real event.