Skip to main content
SendPost signs a webhook request with HMAC-SHA256 when the webhook has a signing secret. Verify the signature to confirm that the request came from SendPost and that the payload hasn’t been altered in transit.
Webhooks are not signed with your Account API Key. Since May 2026 a webhook request is signed only when the webhook has its own secret; a webhook without a secret is delivered without signature headers. If your endpoint verifies signatures with your API key, set a secret on the webhook and verify with that secret instead.

Set a Signing Secret

You choose the secret. Use a long random value, for example the output of openssl 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 secret when you create or update a webhook. On update, leaving secret out keeps the current secret, and "secret": "" removes it, so the webhook is delivered unsigned.
Leading and trailing spaces are removed from the secret before it is stored.

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:
  1. Make your endpoint accept a signature computed with either the old or the new secret.
  2. Set the new secret with Update Webhook.
  3. 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:
  1. Extract the signature from the X-SendPost-Signature header
  2. Read the raw request body (as bytes/string, before any JSON parsing)
  3. Compute HMAC-SHA256 of the request body using the webhook’s secret as the key
  4. Hex-encode the computed signature
  5. Compare the computed signature with the header value using a constant-time comparison
If the signatures match, the webhook is authentic and unaltered.
Always use constant-time comparison when comparing signatures to prevent timing attacks. Never use simple string equality (== or ===).

Code Examples

Each example reads the webhook’s secret from the SENDPOST_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 a webhookEndpoint, 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:
  1. Create an account webhook with exactly that URL and a secret.
  2. Set enabled: false unless the URL should also receive events for all your other emails. A disabled webhook still supplies its secret.
  3. Verify requests to that URL with that webhook’s secret.
A 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

Critical: Always use the raw request body (as bytes/string) for signature verification, not the parsed JSON object. The signature is computed on the exact bytes sent by SendPost.
  • 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

The X-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

  1. Set a secret on every webhook and verify signatures before processing webhook data
  2. Use constant-time comparison to prevent timing attacks
  3. Store your webhook secret securely (environment variables, secret management services)
  4. Log verification failures for security monitoring
  5. 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:
Body:
The signature in 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.