Webhook Security: Signatures, Replay Checks, and Idempotency

Understanding Webhook Security Risks

Webhook endpoints are fundamentally unauthenticated HTTP receivers exposed to the public internet. Without cryptographic verification, any client can send a POST request to your endpoint, claiming to be a trusted provider like Stripe or GitHub. This open design makes webhooks vulnerable to spoofing, where an attacker forges events—such as a successful payment notification—to manipulate application state without authorization.

In addition to spoofing, webhook endpoints face the risk of replay attacks. An attacker who intercepts a legitimate, signed webhook payload can resend that exact payload to your endpoint. If your system relies solely on signature verification, the replayed request will appear valid because the signature matches the payload. To mitigate these threats, robust webhook implementations require a combination of HMAC signature verification, timestamp validation, and strict idempotency controls.

HMAC Signature Verification

The primary defense against webhook spoofing is Hash-based Message Authentication Code (HMAC) signature verification. When a provider sends a webhook, they generate an HMAC signature using a shared secret and the exact raw HTTP request body, placing the resulting hash in a designated HTTP header. Your application must independently compute the HMAC signature using the same shared secret and the raw request body it received, comparing its computed hash to the provided signature.

A critical failure mode in signature verification involves mutating the request body before computing the hash. Frameworks often automatically parse incoming JSON payloads, reordering keys, stripping whitespace, or altering character encoding. For example, if an Express.js application applies `express.json()` middleware before the webhook verification route, the raw request body is lost. The verification must occur on the exact UTF-8 string transmitted by the provider. If the computed hash does not match the provided signature, the request must be rejected immediately with a 400 Bad Request status.

• Retrieve the exact raw HTTP request body as a string or buffer.
• Extract the signature from the designated HTTP header (e.g., `Stripe-Signature`).
• Compute the HMAC SHA-256 hash using your endpoint's specific signing secret.
• Perform a constant-time string comparison to prevent timing attacks.

Preventing Replay Attacks

While HMAC signatures verify the authenticity and integrity of a payload, they do not inherently prevent replay attacks. A captured payload and its valid signature can be submitted multiple times. To defend against this, webhook signatures typically incorporate a timestamp. For instance, the `Stripe-Signature` header includes a `t=` parameter representing the Unix timestamp of when the event was generated. The signature is computed over a concatenated string of this timestamp and the payload.

To enforce replay protection, your application must extract the timestamp from the signature header and compare it to the current system time. If the timestamp is older than an acceptable tolerance window—commonly five minutes—the request should be rejected, even if the signature is mathematically valid. This narrow window limits the timeframe during which an intercepted payload can be successfully replayed. However, clocks must be reasonably synchronized via NTP to avoid falsely rejecting legitimate requests due to time drift.

Designing Idempotent Event Handlers

Webhook delivery is inherently at-least-once. Providers will automatically retry failed deliveries, and network anomalies can result in duplicate events arriving at your endpoint. Consequently, processing the same webhook event multiple times must not result in unintended side effects, such as double-crediting an account or sending duplicate emails. Your event handlers must be strictly idempotent.

Idempotency is typically achieved by tracking unique event identifiers provided in the webhook payload. Before executing any state-changing logic, your application should query its datastore to determine if the event ID has already been processed. If the event is marked as processed, the handler should safely skip execution and return a 200 OK status to acknowledge receipt and halt further retries by the provider.

• Extract the unique event ID from the verified webhook payload.
• Check a transactional datastore to see if the event ID exists.
• If the event is new, record the event ID and process the payload transactionally.
• If the event exists, return a successful HTTP response without reprocessing.

Handling Concurrent Deliveries

A subtle but dangerous edge case in idempotent webhook processing is concurrent delivery. A provider might send multiple identical webhook requests simultaneously, or an automated retry might arrive while the initial request is still being processed. If the idempotency check is not thread-safe, multiple threads might query the datastore simultaneously, find that the event has not been processed, and execute the side effects concurrently, bypassing the idempotency protection.

To prevent concurrent processing anomalies, the idempotency implementation must use atomic operations or distributed locks. When an event is received, the system should atomically attempt to insert the event ID into the datastore or acquire a lock associated with the event ID. If the insertion fails due to a unique constraint violation, or the lock cannot be acquired, the system knows another thread is handling the event. The application can then either return a 409 Conflict to trigger a delayed retry or wait for the concurrent process to complete before returning a 200 OK.

Safe Test Matrix and Expected Outcomes

Validating a webhook integration requires testing various payload and signature combinations to ensure the security controls reject malicious traffic while accepting legitimate events. A comprehensive test matrix should cover missing signatures, invalid signatures, expired timestamps, and duplicate payloads.

Below is a synthetic test matrix outlining scenarios and their expected outcomes when testing a webhook endpoint implementation. These tests should be executed using automated fixtures in a staging environment.

• Scenario: Valid payload, valid signature, current timestamp. Expected: 200 OK, event processed.
• Scenario: Valid payload, missing signature header. Expected: 400 Bad Request, event rejected.
• Scenario: Modified payload, signature matching original payload. Expected: 400 Bad Request, signature mismatch.
• Scenario: Valid payload, valid signature, timestamp 10 minutes old. Expected: 400 Bad Request, tolerance exceeded.
• Scenario: Exact duplicate of previously processed valid request. Expected: 200 OK, event skipped (idempotency).

Implementation Tradeoffs and Failure Modes

When implementing webhook security, engineering teams must balance strict security controls with operational resilience. One tradeoff involves the strictness of the timestamp tolerance window. A very narrow window (e.g., 30 seconds) provides strong replay protection but increases the risk of falsely rejecting legitimate webhooks if the provider experiences delivery latency or if the receiving server's clock drifts. A wider window (e.g., 5 minutes) accommodates latency and minor clock drift but slightly expands the replay vulnerability window.

A common failure mode occurs when applications attempt to parse the request body before verifying the signature. If a framework's middleware parses the JSON payload and the application then serializes it back to a string for verification, minor formatting differences (like whitespace or key ordering) will alter the resulting string. Because HMAC is highly sensitive to input changes, the computed signature will not match the provided signature, leading to persistent verification failures for legitimate webhooks. Verification must always be performed on the raw, unmodified byte stream received from the network.

Sources

Drafted with Gemini and checked for source links, advisory identifiers, structure and unsupported product claims. Examples are synthetic and are not scan results.

Drafted with Gemini and checked for source links, advisory identifiers, structure and unsupported product claims. Examples are synthetic and are not scan results.

• Stripe: Manage webhook endpoints
• Primary reference: docs.stripe.com