Webhook Signature

Overview

A webhook signature is a cryptographic value that lets a receiver verify selected event bytes and metadata using trusted key material. Webhook Signature is cryptographic evidence attached to a delivery so the consumer can test authenticity and integrity; it is not the verification procedure itself. Providers commonly use an HMAC with a shared secret or an asymmetric signature with a private key. A signature does not encrypt the payload or prevent replay by itself. Verification fails when middleware changes bytes, canonicalization differs, or the wrong key and algorithm are used. Receivers should implement the documented algorithm exactly, preserve raw bytes, select trusted keys, compare safely, and enforce timestamp and replay controls. The signed message may include the raw body, timestamp, event identifier, version, or other canonical fields. If critical fields are excluded, attackers may alter them without invalidating the signature. Key rotation, test vectors, and negative tests should cover malformed headers, duplicate values, and altered payloads. Monitoring for Webhook Signature should track delivery age, signature failures, duplicate rate, retry exhaustion, and unresolved business events. Recovery for Webhook Signature should combine replay controls with an authoritative status check rather than trusting delivery history alone.

For Webhook Signature, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing.

A receiver should treat transport acknowledgement and successful downstream processing as separate states for Webhook Signature.

The Webhook Signature path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.

A Webhook Signature handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.