Webhook Signature Verification
Pronunciation: WEB-hook SIG-nuh-cher vair-ih-fih-KAY-shun
Definition
Webhook signature verification checks whether a received webhook payload was authenticated using the provider’s specified cryptographic scheme and shared secret or public key.
Overview
What it means
Webhook signature verification checks whether a received webhook payload was authenticated using the provider’s specified cryptographic scheme and shared secret or public key. It helps reject forged events pretending that a customer has paid.
How it works
The receiver computes or verifies a signature over exactly the documented bytes, often including a timestamp and the raw HTTP request body. It compares signatures securely, checks allowed timestamp skew when specified, and chooses the correct active signing key. Parsers must not reserialize JSON before hashing if the provider signs raw bytes.
Understanding the technical details
Use the provider’s exact canonicalization instructions: a JSON parser can rearrange whitespace or keys, invalidating an HMAC computed over a reconstructed payload. Check the signature against the original raw bytes and applicable timestamp tolerance. During secret rotation, support the overlap window explicitly and retire old credentials deliberately. Never trust an unsigned event merely because its IP address appears familiar. Separately verify the invoice resource and current state before taking a high-risk action.
Additional protocol context
Verification alone does not establish freshness, authorization for every business transition, or payload correctness. Replayed valid messages remain valid cryptographically. Loose parsing, algorithm confusion, untrusted key identifiers, and non-constant comparison can weaken implementation.
Implementations should enforce approved algorithms and keys, exact canonicalization, bounded timestamp skew, replay detection, and safe comparison. Verification must happen before trusting parsed fields. After success, schema, resource identity, amount, status, and legal transition still require validation. Test vectors should cover every supported key version.
Common failures and limitations
A valid signature proves the message came from a party holding signing credentials; it does not prove the event is unique, fresh or still the latest invoice state. Protect against replays and rotate secrets safely. Always follow the exact provider signature specification.
Related concepts
Webhook, Webhook Verification, Merchant API Key.
Further reading
Example
A forged request claims invoice 771 is paid. The merchant’s server computes the expected HMAC using its webhook secret and sees that the signature does not match, so it refuses to trigger fulfillment.
Comparison
Webhook signature verification authenticates a delivered message. API authentication protects requests merchants send to providers; deduplication prevents repeating already processed events.
Key Takeaway
A valid signature proves the message came from a party holding signing credentials; it does not prove the event is unique, fresh or still the latest invoice state.
Sources
- NIST Documentation: Cryptographic Standards And Guidelines — NIST (2026-07-30)
- OxaPay Documentation: Webhook — OxaPay (2026-07-30)
- Stripe Documentation: Webhooks — Stripe (2026-07-30)