Securing webhook handlers used by agents: how do I verify signatures (X-Hub-Signature-256, Stripe-Signature), avoid 'signature mismatch' errors, and prevent replayed or duplicate events?

Cause: A webhook endpoint is a public URL. Without verification anyone can post fake events that trigger agent actions (fulfilling orders, running jobs, changing records). Valid captured requests can also be sent again (replay), and providers may legitimately deliver the same event more than once. Fix (best first): 1. Verify the signature on every request, before acting. Keep a high-entropy shared secret in a secret store, never in source control. GitHub sends X-Hub-Signature-256, a sha256= prefixed HMAC-SHA256 hex digest of the payload; Stripe sends Stripe-Signature with a timestamp and v1 signature, computed over the timestamp, a dot and the body. Prefer the provider's official library or helper. 2. Use the raw request body. Both providers' docs stress this: if your framework parses and re-serializes JSON, or a proxy or load balancer alters the body or headers, the computed signature will not match. Read the raw bytes first, verify, then parse. 3. Compare in constant time (for example crypto.timingSafeEqual or hmac.compare_digest), not with ==. Reject missing or malformed headers, and ignore deprecated signature schemes such as GitHub's older SHA-1 header or Stripe schemes other than v1. 4. Prevent replay. Stripe signs a timestamp, and its libraries reject events older than a default 5-minute tolerance; never set tolerance to 0, which disables the check, and keep server clocks synced with NTP. GitHub's validation page does not describe a timestamp, so also record each delivery's unique id and refuse ids you have already processed. 5. Make handlers idempotent. Log processed event ids and skip repeats; do not rely on arrival order, since providers like Stripe state events can arrive out of order. 6. Return a 2xx quickly and do slow work asynchronously from a queue, so the provider does not time out and retry. 7. Support secret rotation: Stripe lets two secrets be active during a roll, so accept either during the overlap. Rotate immediately if a secret leaks. 8. Optionally restrict by source IP where the provider publishes ranges, as an extra layer, not a replacement for signatures. Verify: A request with a wrong or missing signature gets a 4xx and triggers nothing; a correctly signed request works; resending the same delivery causes no second action; an old timestamp is rejected. GitHub publishes a test secret and payload with the expected digest to check your implementation. Sources: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries https://docs.stripe.com/webhooks