Verify webhook signatures
Webhooks let the platform push events (such as delivery, open, click, bounce, and unsubscribe notifications) to an endpoint you host. Because that endpoint is public, you should verify each request's signature before trusting it. Verification confirms the request came from the platform and that its body was not altered in transit.
Before you begin
- A registered webhook endpoint and its signing secret. Find and copy this in your account's webhook or integration settings (confirm the exact steps in your account).
- The ability to read the raw, unparsed request body and the signature header your endpoint receives.
- Store the signing secret as a server-side secret (environment variable or secrets manager) — never in client code or version control.
Steps
- On each incoming request, capture the raw request body exactly as received. Do not re-serialize parsed JSON — even whitespace changes will break verification.
- Read the signature header from the request. It typically carries a keyed hash (commonly HMAC-SHA256) of the body, and often a timestamp.
- Recompute the expected signature: apply HMAC-SHA256 to the raw body (concatenated with the timestamp, if your account's scheme includes one) using your signing secret.
- Compare your computed value to the header value using a constant-time comparison to avoid timing attacks. Do not use a plain string equality check.
- If a timestamp is present, reject requests whose timestamp is outside a small tolerance (for example, five minutes) to limit replay attacks.
- Only after the signature matches should you process the payload. Respond quickly with a 2xx status; do heavy work asynchronously.
Result
Requests with a valid signature are accepted and processed; requests with a missing or mismatched signature are rejected (return 401 or 403). Test by sending a request with a tampered body or wrong secret and confirming your endpoint rejects it.
Related
Canonical terms: Author, Edition, Folder (Project Folder), Broadcast. See the Glossary.