Webhooks
Receive and verify signed delivery, open, click, and bounce events.
Webhooks deliver email events asynchronously. Delivery can be delayed or retried,
so your endpoint should respond promptly and handle duplicate deliveries.
Register an HTTPS endpoint with POST /v1/webhooks
and subscribe to events from the catalog (or ["*"] for all).
Test before activation
A new endpoint is saved inactive. No customer events go to it until it
passes a signed verification test. Copy the signing secret returned at creation,
configure your receiver, then click Verify and activate in the dashboard or
call POST /v1/webhooks/{id}/verify with a webhooks:write key.
The test is a signed webhook.test POST with data.challenge. After checking
the signature, respond with HTTP 2xx and the challenge string as the entire
plain-text response body. For example, in an Express handler after reading
the raw body and validating its signature:
const event = JSON.parse(rawBody);
if (event.type === 'webhook.test') {
return res.status(200).type('text/plain').send(event.data.challenge);
}
// Process real events only after this branch.A 404, timeout, redirect, or wrong response keeps the endpoint inactive and returns an error explaining why. Updating the URL also pauses delivery until the new address passes verification. A successful test confirms that the endpoint accepted and processed this challenge; it cannot guarantee future availability.
The event payload
{
"id": "evt_...",
"type": "email.delivered",
"created_at": "2026-07-22T10:00:00Z",
"data": {
"message_id": "...",
"to": ["[email protected]"],
"subject": "Hello from SendMailOS"
}
}Common types: email.sent, email.delivered, email.opened,
email.clicked, email.bounced, email.complained, email.suppressed.
Verifying signatures
Deliveries carry svix-compatible headers, and the signing secret (whsec_…) is
returned in full only when you create the endpoint. Always verify before
trusting a payload.
| Header | Purpose |
|---|---|
webhook-id | Unique delivery id |
webhook-timestamp | Unix seconds — reject if older than 5 minutes |
webhook-signature | v1,<base64 HMAC-SHA256> over {id}.{timestamp}.{body} |
import crypto from 'node:crypto';
function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
if (!id || !ts || !secret.startsWith('whsec_')) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
const signed = `${id}.${ts}.${rawBody}`;
const key = Buffer.from(secret.split('_')[1], 'base64');
const expected = crypto.createHmac('sha256', key).update(signed).digest('base64');
return (headers['webhook-signature'] ?? '')
.split(' ')
.some((sig) => {
const [version, value] = sig.split(',');
if (version !== 'v1' || !value) return false;
const actual = Buffer.from(value, 'base64');
const wanted = Buffer.from(expected, 'base64');
return actual.length === wanted.length &&
crypto.timingSafeEqual(actual, wanted);
});
}Verify against the raw request body, before any JSON parsing — re-serializing changes the bytes and breaks the signature.
Retries & deliveries
Failed deliveries retry at 1m, 5m, 30m, 2h, and 5h. An endpoint that fails for
five days is disabled. Inspect and replay attempts with
GET /v1/webhooks/{id}/deliveries and
rotate the secret with
POST /v1/webhooks/{id}/rotate-secret.