Know the moment something happens to your email

curl https://api.mailbay.dev/v1/webhooks \
  -H "Authorization: Bearer $MAILBAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/mailbay", "event_types": ["message.received"]}'

# {"id": "whk_01jbz...", "url": "https://example.com/hooks/mailbay",
#  "event_types": ["message.received"], "inbox_id": null, "secret": "whsec_..."}
# Save the secret now. It is shown only once.

{
  "id": "evt_01jbz9c4m7r2k8t6w3x5y0z1a2",
  "type": "message.received",
  "timestamp": "2026-10-13T09:41:07.512Z",
  "data": {
    "message_id": "msg_01jbz9c3...",
    "inbox_id": "ibx_01jbz8w4k2q9",
    "thread_id": "thr_01jbz9c3...",
    "from": "noreply@github.com",
    "subject": "Your GitHub launch code"
  }
}

import crypto from "node:crypto";

// secret: the whsec_... value from when you created the webhook.
// body: the raw request body as text, before any JSON parsing.
export function verifyWebhook(secret, headers, body) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) throw new Error("missing webhook headers");

  // Reject old timestamps, so a captured request cannot be replayed.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) throw new Error("timestamp too old");

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

  // The header holds one or more space separated "v1,<base64>" signatures.
  const ok = signatures.split(" ").some((s) => {
    const [version, sig] = s.split(",");
    if (version !== "v1" || !sig) return false;
    const given = Buffer.from(sig, "base64");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
  if (!ok) throw new Error("invalid signature");
  return JSON.parse(body);
}

# What happened to each call? Newest first.
curl https://api.mailbay.dev/v1/webhooks/whk_01jbz.../deliveries \
  -H "Authorization: Bearer $MAILBAY_API_KEY"

# Send one event again, right now. It answers 202.
curl -X POST https://api.mailbay.dev/v1/webhooks/whk_01jbz.../deliveries/DELIVERY_ID/replay \
  -H "Authorization: Bearer $MAILBAY_API_KEY"