SendMailOS
Guides

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.

HeaderPurpose
webhook-idUnique delivery id
webhook-timestampUnix seconds — reject if older than 5 minutes
webhook-signaturev1,<base64 HMAC-SHA256> over {id}.{timestamp}.{body}
Node — verify
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.

On this page