Send your first email, then read the reference.

{
  "from": "Acme <hello@acme.dev>",
  "to": ["you@example.com", "cc-fallback@example.com"],
  "subject": "Your receipt from Acme",
  "html": "<p>Thanks for your order.</p>",
  "text": "Thanks for your order.",
  "reply_to": "support@acme.dev",
  "headers": { "X-Entity-Ref-ID": "order_8841" },
  "tags": [{ "name": "category", "value": "receipt" }],
  "scheduled_at": "2026-10-01T09:00:00Z"
}

{ "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" }

[
  { "from": "Acme <hello@acme.dev>", "to": "a@example.com", "subject": "Hi A", "html": "<p>Hi A</p>" },
  { "from": "Acme <hello@acme.dev>", "to": "b@example.com", "subject": "Hi B", "html": "<p>Hi B</p>" }
]

{
  "data": [
    { "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" },
    { "id": "em_2wR8vLp1kNs5tG3xC9hQ7mB" }
  ]
}

{
  "object": "email",
  "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC",
  "to": ["you@example.com"],
  "from": "Acme <hello@acme.dev>",
  "created_at": "2026-09-25T09:00:12.481Z",
  "subject": "Your receipt from Acme",
  "html": "<p>Thanks for your order.</p>",
  "text": "Thanks for your order.",
  "bcc": null,
  "cc": null,
  "reply_to": ["support@acme.dev"],
  "last_event": "delivered",
  "scheduled_at": null,
  "tags": [{ "name": "category", "value": "receipt" }]
}

{ "scheduled_at": "2026-10-01T12:00:00Z" }

{ "object": "email", "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" }

{ "object": "email", "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" }

{ "name": "acme.dev", "region": "eu-west-1" }

{
  "object": "domain",
  "id": "dom_4kP1qR9zL7vT2yB6wC0nS3x",
  "name": "acme.dev",
  "status": "not_started",
  "created_at": "2026-09-25T09:00:12.481Z",
  "region": "eu-west-1",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "records": [
    { "record": "DKIM", "type": "TXT", "name": "irisend._domainkey", "value": "p=MIGfMA0GCSq...", "ttl": "Auto", "status": "not_started", "required": true },
    { "record": "SPF", "type": "MX", "name": "send", "value": "feedback-smtp.eu-west-1.amazonses.com", "priority": 10, "ttl": "Auto", "status": "not_started", "required": true },
    { "record": "SPF", "type": "TXT", "name": "send", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "not_started", "required": true },
    { "record": "DMARC", "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "not_started", "required": false }
  ]
}

{ "name": "Production", "permission": "full_access" }

{ "id": "3f9c2b1a-6e2d-4a3f-9c0b-1a2b3c4d5e6f", "token": "ir_8fK3mQ1z_9pR2vT6yB4wL0nC7xE1sH5dJ" }

{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "3f9c2b1a-6e2d-4a3f-9c0b-1a2b3c4d5e6f", "name": "Production", "created_at": "2026-09-25T09:00:12.481Z", "last_used_at": "2026-09-25T10:03:41.220Z" }
  ]
}

{
  "endpoint": "https://acme.dev/webhooks/irisend",
  "events": ["email.delivered", "email.bounced", "email.complained"]
}

{
  "object": "webhook",
  "id": "wh_3xC7qR1vN9sL4yB2wT8hM0z",
  "signing_secret": "whsec_MfKzB3n2Rp9vQwL7xC1sH5tY"
}

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook",
      "id": "wh_3xC7qR1vN9sL4yB2wT8hM0z",
      "endpoint": "https://acme.dev/webhooks/irisend",
      "events": ["email.delivered", "email.bounced", "email.complained"],
      "status": "enabled",
      "created_at": "2026-09-25T09:00:12.481Z"
    }
  ]
}

{
  "object": "webhook",
  "id": "wh_3xC7qR1vN9sL4yB2wT8hM0z",
  "endpoint": "https://acme.dev/webhooks/irisend",
  "events": ["email.delivered", "email.bounced", "email.complained"],
  "status": "enabled",
  "created_at": "2026-09-25T09:00:12.481Z",
  "signing_secret": "whsec_MfKzB3n2Rp9vQwL7xC1sH5tY"
}

{ "object": "webhook", "id": "wh_3xC7qR1vN9sL4yB2wT8hM0z", "deleted": true }

{
  "type": "email.delivered",
  "created_at": "2026-09-25T09:01:04.112Z",
  "data": {
    "email_id": "em_9f2K3mQ1zPr7vT6yB4wL0nC",
    "from": "Acme <hello@acme.dev>",
    "to": ["you@example.com"],
    "subject": "Your receipt from Acme",
    "created_at": "2026-09-25T09:00:12.481Z",
    "tags": { "category": "receipt" }
  }
}

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

function verifyIrisendWebhook(
  secret: string,
  headers: Record<string, string | undefined>,
  body: string,
): boolean {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];
  if (!id || !timestamp || !signature) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${body}`)
    .digest("base64");

  // headers may carry several space-separated "v1,<sig>" values during rotation
  return signature.split(" ").some((part) => {
    const candidate = Buffer.from(part.replace(/^v1,/, ""));
    const target = Buffer.from(expected);
    return candidate.length === target.length && timingSafeEqual(candidate, target);
  });
}