Webhook Payload Validator

Verify the signature before parsing anything

A webhook endpoint is a public URL that accepts data and usually acts on it. Without verification, anyone who learns the URL can send a fabricated payment-succeeded event. Providers sign each request with an HMAC over the raw body using a shared secret, and the receiver recomputes it. The critical detail is raw body: many frameworks parse JSON before your handler runs, and re-serialising changes whitespace and key order, so the recomputed signature never matches. Capturing the raw bytes before any middleware touches them is the fix, and it is the single most common cause of signature verification failing against a correct implementation.

Compare signatures in constant time

Use the platform's constant-time comparison rather than string equality, for the same timing reasons that apply to any secret comparison.

Timestamps stop replay

A valid signed request captured in transit stays valid forever unless something limits it. Providers include a timestamp in the signed payload; reject anything outside a tolerance window of about five minutes. Recording processed event IDs closes the remaining gap and gives you idempotency at the same time.

Delivery is at-least-once, never exactly-once

Every provider retries on failure, and retries happen after successful processing when your acknowledgement is lost. Duplicate deliveries are normal, not exceptional. Handlers must be idempotent: key on the provider's event ID, record it, and make a repeat a no-op. Any handler that increments a balance or sends an email without this will eventually do it twice.

Order is not guaranteed

Retries and parallel delivery mean events can arrive out of sequence — a subscription.updated before the subscription.created it depends on. Handle each event on its own terms, and where order genuinely matters, fetch current state from the provider's API rather than reconstructing it from the event stream.

Acknowledge fast, process later

Providers time out quickly, commonly at five to ten seconds, and a timeout counts as a failure that triggers retries. Doing real work inside the handler creates a loop where slow processing causes duplicates that make processing slower. Validate, persist, return 200, and process from a queue. Return a 2xx only when you have durably accepted the event, and a 5xx when you want the retry.