Webhooks

Webhooks push events to your HTTPS endpoint as they happen. Deliveries follow the Standard Webhooks scheme, and the same headers are also sent with the svix- prefix, so existing Standard Webhooks or Svix verification libraries work unchanged.

Create a webhook

curl -s -X POST https://api.162-55-213-24.sslip.io/v0/webhooks \
  -H "Authorization: Bearer $MAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://agent.your-domain.eu/hooks/mail", "event_types": ["message.received", "message.security.review"]}'

The response contains the signing secret (whsec_...). It is returned only once. Optionally restrict a webhook to up to 10 inboxes with inbox_ids.

Event types

Payload

Message events carry the message and its thread. domain.verified carries the domain. Sending pause events carry the inbox or organization, the reason and the counts that tripped the breaker.

{
  "type": "event",
  "event_type": "message.received",
  "event_id": "5f0c7a2e-6b1d-4a57-9d1e-2f9a1c3b8e44",
  "created_at": "2026-10-22T09:41:07Z",
  "data": {
    "message": { "id": "...", "inbox_id": "billing@agents.your-domain.eu", "subject": "Invoice 2026-118", "labels": ["received", "unread"] },
    "thread": { "thread_id": "...", "message_count": 1 }
  }
}

With screen before notify, on by default for every organization, message.received fires only after the gatekeeper verdict is clear: first message.security.completed, then message.received. A message held for review fires only message.security.review, with text, html, extracted_text and previews left out, and fires message.received once a key with message_release releases it. Deliveries leave in event order on the first attempt; retries can arrive later than newer events. If an operator turns the setting off, message.received fires at ingest while the gatekeeper may still be running.

Signature

The signature is an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64 decoded part of the secret after whsec_. Reject timestamps more than 5 minutes away from your clock, and compare in constant time. Verify against the raw body bytes: parsing and re-serializing JSON changes them.

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

const TOLERANCE_SECONDS = 5 * 60;

/** body must be the raw request body, exactly as received. */
export function verifyWebhook(secret: string, headers: Headers, body: string): boolean {
  const id = headers.get("webhook-id");
  const timestamp = headers.get("webhook-timestamp");
  const signatures = headers.get("webhook-signature");
  if (!id || !timestamp || !signatures) return false;

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;

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

  return signatures.split(" ").some((candidate) => {
    const got = Buffer.from(candidate);
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify_webhook(secret: str, headers, body: bytes) -> bool:
    """headers: a case insensitive mapping; body: the raw request bytes."""
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature", "")
    if not msg_id or not timestamp:
        return False
    try:
        if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
            return False
    except ValueError:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()
    return any(hmac.compare_digest(sig, expected) for sig in signatures.split())

Delivery and retries

• Any 2xx status within 15 seconds counts as delivered. Redirects are not followed.
• Failed deliveries are retried after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, then marked failed.
• Events can arrive more than once and out of order. Deduplicate with webhook-id and read the current state from the API when order matters.
• Webhook URLs must be HTTPS and resolve to public addresses. Private, loopback and link local addresses are refused.

Event stream

For live updates without a public endpoint, open GET /v0/events/stream with a key holding message_read. It is a Server Sent Events stream: each event has an id, the event type as event and the webhook body above as data, with the same redaction for held mail. Narrow it with ?types=message.received,message.sent and ?inbox=<address>. A client that reconnects with Last-Event-ID (EventSource does this for you) continues after that event; without it the stream starts with new events.

curl -N https://api.162-55-213-24.sslip.io/v0/events/stream?types=message.received \
  -H "Authorization: Bearer $MAI_API_KEY"

• Up to 5 open streams per API key; more return 429 too_many_streams.
• An idle stream gets a : ping comment every 15 seconds, so proxies keep it open.
• A revoked or expired key loses its open streams within a minute.
• Delivery is at least once: deduplicate with event_id. Use webhooks when events must reach you while no client is connected.

Endpoints