Verifying Webhook Signatures Before Processing Events
Verify webhook authenticity using the documented signature scheme, original request bytes and replay controls before accepting data into a workflow.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A webhook endpoint receives untrusted HTTP input. Signature verification establishes a limited authenticity property under the sender’s documented scheme; it does not automatically make every decoded event complete or final.
Verify the correct bytes
Many schemes sign the raw request body or a canonical message containing it. Parsing and reserialising JSON before verification can change those bytes. Follow the exact scheme, select the intended secret version and compare signatures using an appropriate constant-time primitive. Bound request size before expensive processing.
Worked example: equivalent JSON, different bytes
Bodies with different whitespace can decode to the same object but produce different message digests. If the sender signs original bytes, verifying a reserialised object rejects a valid delivery or validates the wrong representation. Capture the bounded raw body for verification, then parse it only after the authenticity check succeeds.
Add replay and delivery handling
Where the scheme includes a timestamp, enforce its documented validity policy with reasonable clock handling. Deduplicate delivery or event IDs according to the sender contract. Test wrong secrets, rotation overlap, repeated delivery and malformed signatures. Never log the signing secret. Authentication and business validation remain separate steps.
A practical acceptance test
Sign one exact body and then change only JSON whitespace before verification. Under a raw-body signing scheme, the changed bytes must fail even if they parse to the same object. Test old and new secret versions under the rotation policy. Repeated valid delivery must still pass through deduplication rather than invoke fulfilment twice.
Questions about the topic
Frequently asked questions
Should JSON be reserialised before verification?
Only if the documented scheme explicitly requires that canonicalisation.
Does a valid signature prevent repeated delivery?
No. Replay and deduplication require separate controls.
Standards & technical documentation