technical · sourced answer
Webhook Signature Verification
Webhook signature verification is a security process where a receiver validates a cryptographic signature attached to an incoming HTTP request. This ensures the payload was sent by the trusted provider and was not altered during transit.
Definition
Webhook signature verification is a mechanism used to authenticate the source of a webhook event. When a provider like Resend or SendGrid sends a notification about an email event, they include a hash of the payload signed with a secret key. The receiving server uses the same secret key to recalculate the hash and compare it to the signature provided in the request header.
Mechanical Process
The provider generates a HMAC hash using a shared secret and the request body. This hash is sent in a header, often named X-Signature or similar. The receiver captures the raw request body and the signature header. The receiver then computes its own HMAC hash using the shared secret. If the computed hash matches the header value, the request is authentic. If they differ, the request is rejected as unauthorized.
Importance for Senders
Without verification, any entity that knows your webhook URL can send fake data to your server. This could lead to incorrect database updates, such as marking a delivered email as bounced. Implementing verification prevents spoofing attacks and ensures that your application only reacts to legitimate events triggered by your email infrastructure.
Operational Notes
A common mistake is parsing the request body into a JSON object before verifying the signature. Because JSON parsers can change whitespace or key order, the resulting string may not match the original payload used by the provider. Always use the raw, unparsed request body for HMAC calculations to avoid verification failures.
Implementation Example
In a Node.js environment, a developer would use the crypto module to create an hmac sha256 hash of the raw body using the provider secret. This result is then compared to the signature header using a constant time comparison function to prevent timing attacks. SendHQ provides free tools at https://sendhq.cc/tools to help manage various email configurations that often precede webhook setup.
Questions teams ask
What happens if the secret key is leaked?
If the secret key is compromised, an attacker can sign fake requests that your server will accept as valid. You must rotate the secret key immediately in your provider dashboard and update your server environment variables.
Does HTTPS replace the need for signature verification?
No. HTTPS encrypts the data in transit and verifies the server identity, but it does not verify that the specific client sending the request is your authorized email provider.
Why use HMAC instead of a simple API key?
HMAC signatures prove that the content of the message has not been tampered with. A static API key in a header only proves the sender knows the key, not that the payload is intact.
Primary sources
- Resend Documentation — Resend
- Postmark Developer Documentation — Postmark
- SendGrid Documentation — Twilio SendGrid