Set a Signing Secret
You choose the secret. Use a long random value, for example the output ofopenssl rand -hex 32.
- Dashboard: fill in Webhook Secret (Optional) when you create the webhook. The dashboard can’t change the secret of an existing webhook; use the API for that.
- API: send
secretwhen you create or update a webhook. On update, leavingsecretout keeps the current secret, and"secret": ""removes it, so the webhook is delivered unsigned.
Changing the Secret
Every delivery attempt, retries included, is signed with the secret the webhook has when the attempt is sent. A retry of an event from before the change therefore arrives signed with the new secret. To change the secret without rejecting requests:- Make your endpoint accept a signature computed with either the old or the new secret.
- Set the new secret with Update Webhook.
- Once requests verify with the new secret, remove the old one from your endpoint.
Webhook Headers
Example Webhook Request Headers
Verification Process
To verify a webhook request:- Extract the signature from the
X-SendPost-Signatureheader - Read the raw request body (as bytes/string, before any JSON parsing)
- Compute HMAC-SHA256 of the request body using the webhook’s secret as the key
- Hex-encode the computed signature
- Compare the computed signature with the header value using a constant-time comparison
Code Examples
Each example reads the webhook’s secret from theSENDPOST_WEBHOOK_SECRET environment variable.
JavaScript (Node.js)
Python
Go
Ruby
Java (Spring Boot)
PHP
Per-Email Webhook Endpoints
Send Email and Send Email With Template accept awebhookEndpoint, a URL that receives the events of that one email. A webhookEndpoint can’t carry a secret. A request to it is signed only when its URL exactly matches the URL of a webhook on your account that has a secret: same scheme, host, path, trailing slash and query string.
To get signed requests on a webhookEndpoint URL:
- Create an account webhook with exactly that URL and a secret.
- Set
enabled: falseunless the URL should also receive events for all your other emails. A disabled webhook still supplies its secret. - Verify requests to that URL with that webhook’s secret.
webhookEndpoint receives every event of its email except Validation, whatever events the matching webhook is set to receive. If the matching webhook is enabled, it also receives the email’s events as an account webhook, so the URL gets those events twice. Use event.eventID to drop the duplicates.
If the URL changes from email to email, use one account webhook with a secret instead, and route events on your side with the email’s groups or the recipient’s customFields. Both come back in the emailMessage part of each event.
Important Considerations
Request Body Handling
- Do: Read the raw body before parsing JSON
- Don’t: Parse JSON first and then try to verify the signature
- Do: Preserve the exact byte sequence received
- Don’t: Modify, prettify, or re-encode the body
Which Secret to Use
Verify with the secret of the webhook the request was sent to. If your webhooks have different secrets, each one’s requests are signed with its own. Your Account API Key and Sub-Account API Keys are never used for signing.Retry Attempts
TheX-SendPost-Webhook-Attempt header indicates which retry attempt this is. SendPost will retry failed webhook deliveries for up to 10 hours. Each retry will have the same payload but a different attempt number.
Security Best Practices
- Set a secret on every webhook and verify signatures before processing webhook data
- Use constant-time comparison to prevent timing attacks
- Store your webhook secret securely (environment variables, secret management services)
- Log verification failures for security monitoring
- Reject requests without signatures once the webhook has a secret
Example Webhook Payload
Here’s an example of a webhook request with signature headers: Headers:X-SendPost-Signature is computed from the exact JSON body above using the webhook’s secret.
For more information about webhook events and payloads, see SendPost Webhook Object.