Webhooks

Register an endpoint

From Settings → Webhooks, Add endpoint opens a dialog asking for a URL and which of the ten event types to subscribe to — the picker starts empty, the same least-privilege default an API key’s own permissions start from:

On creation, the panel shows you the signing secret exactly once — the same guarantee an API key carries: it is stored in no column at all, so if you lose it, the only way to see it again is to rotate it, which also invalidates the previous one. Closing without copying it asks you to confirm, since there is no way back to this screen afterward.

Copy it right then. Afterward, the panel lists the endpoint alongside any others this organization has registered, flagged only when something needs attention — failing or paused, never a plain “active” badge on a healthy one — with a menu to view its deliveries, edit its URL or events, pause or resume it, or remove it. Rotating the secret lives one level in, on the endpoint’s own detail screen, opened from its row:

Verify the signature

Every delivery arrives as a POST with this header:

webhook-signature: v1=<hex signature>

The signature is HMAC-SHA256(secret, body), computed over the exact bytes of the body — not over your own re-serialized version of the JSON, which may not match what we sent byte for byte. Verify it against the raw body, before parsing it:

import { createHmac, timingSafeEqual } from "node:crypto"

function isValidSignature(rawBody, header, secret) {
  const [scheme, signature] = header.split("=")
  if (scheme !== "v1" || signature === undefined) return false

  const expected = createHmac("sha256", secret).update(rawBody).digest("hex")

  return (
    expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  )
}

v1= is the signature’s own scheme, not an arbitrary separator — it leaves room to introduce a second scheme later without breaking anyone already parsing this one.

Compare with timingSafeEqual, never with ===. An ordinary string comparison stops at the first character that does not match, and that timing difference is information — enough for someone to reconstruct the correct signature one character at a time, probing against your own endpoint.

Payload shape

Every delivery sends this same envelope, frozen at the moment the event happened — never recomputed afterward:

{
  "id": "01a0ba31-3fe4-7cc4-a1c6-64bdaaa5d99c",
  "type": "message.delivered",
  "createdAt": "2026-09-19T12:00:04Z",
  "data": {
    "messageId": "01a0ba31-4a15-7c9a-9b3d-3f1e6c2b7a44",
    "address": "ana@example.com",
    "status": "sent",
    "deliveryStatus": "delivered",
    "occurredAt": "2026-09-19T12:00:03Z",
    "bounceType": "Permanent"
  }
}

The message’s own content and the provider’s internal id never travel in the payload — neither is ours to hand to an endpoint that may be misconfigured.

The ten types

status and deliveryStatus are the same fields GET /v1/email/:messageId returns — a webhook is the other way to learn the same two values, without having to ask.

deliveryStatus is a ladder that never moves backward. A complaint that arrives days after a delivery still wins, regardless of whose own event timestamp is later — which is why a message.complained can arrive after a message.delivered for the same message, and that is correct.