Webhook signature verification steps

This capability turns a provider’s HMAC algorithm and signature header name into a precise, ordered receiver checklist. It does not need your payload, secret, or signature. Use the result while implementing or reviewing an endpoint, then match provider-specific details such as timestamp layout, digest encoding, and replay tolerance against the provider’s own documentation.

Start with the bytes that the provider signed

Signature verification begins before application-level parsing. Preserve the exact request-body bytes as received, because JSON parsing and serialization can change whitespace, key order, escaping, Unicode representation, or line endings while leaving the apparent data unchanged. A correct MAC over changed bytes is still the wrong MAC. Read the named signature header without treating its name as case-sensitive, since HTTP field names are case-insensitive, but apply strict rules to its value. Some providers send a bare digest, while others include a version, timestamp, or several candidate signatures. The generated checklist deliberately tells you to follow that provider-specific grammar instead of guessing. Reject missing, empty, unexpectedly duplicated, or malformed values before doing business work. Keep the endpoint secret in a secret manager or protected runtime binding, never in source code, request logs, error messages, or this tool’s input. The capability needs only the declared HMAC algorithm and header name, so sensitive verification material remains inside your receiver.

Reconstruct, compute, and compare in the right order

After extracting the signature, reconstruct the provider’s signed message exactly. It may be only the raw request body, but many robust schemes sign a timestamp followed by a separator and the body. Use the documented byte order and encoding; do not add a homemade canonicalization step. Compute an HMAC with the endpoint secret and the normalized algorithm shown in the output, then encode the result exactly as required, commonly hexadecimal or Base64. A cryptographically correct digest in the wrong textual encoding will never match. Decode the received and expected values into equal-length byte arrays and compare them with a timing-safe primitive supplied by your platform. Ordinary equality can reveal how much of a signature matched through response timing. A malformed encoding or unequal length is a verification failure, not a reason to truncate or pad either value. Only after the constant-time comparison succeeds should the receiver proceed to freshness, replay, and event-processing checks.

Treat successful cryptography as one part of acceptance

A matching HMAC proves that someone holding the shared secret produced the signed message; by itself, it does not prove that the message is recent or has not already been processed. When the provider signs a timestamp, enforce its recommended tolerance using a reliable server clock. When it supplies a stable event identifier, store accepted identifiers for an appropriate retention window and make processing idempotent. Rotate secrets using the provider’s documented overlap procedure, which may require checking a small bounded set of active secrets or signatures. Reject failures before queuing work or changing state, and return a generic error that does not disclose which verification stage failed. Log a safe reason code, provider name, and request correlation identifier rather than secrets or complete signatures. Test the receiver with untouched payloads, single-byte body changes, stale timestamps, malformed headers, wrong secrets, and replayed events. The generated steps provide the secure order; the provider documentation remains authoritative for its header grammar, signed-payload format, digest encoding, and rotation policy.