Webhooks

Register an HTTPS endpoint and we POST a JSON event to it when something happens. Create webhooks from the dashboard or the API.

#Events

The event catalog in the dashboard (and GET /v1/webhooks/events, no key needed) shows the exact body of every event, in both payload formats.

#Envelope payloads

Set payload: "envelope" on a webhook (or pick Envelope in the dashboard) and message events carry only { inbox_id, thread_id, message_id, from, to, subject, labels, received_at } in data: no bodies, headers, attachments or AI content ever leave in the POST. Your agent fetches the message with GET /v1/messages/:id when it needs it. Draft events carry { inbox_id, thread_id, draft_id, status, to, subject, labels, send_at, sent_message_id, error_code } in the same way, and attachment events { inbox_id, thread_id, message_id, attachment_id, content_type, status, method, pages, error_code }. The default is full when the key may read what the events carry (messages:read for message and attachment events, drafts:read for draft events), else envelope. Asking for full without them is refused (403 insufficient_permissions). Dashboard users can always choose full. Each webhook also reports its last 24 hours (deliveries, failures, error rate, last success and failure) in stats and on its dashboard card.

{
  "id": "evt uuid",
  "type": "message.received",
  "created_at": "2026-09-24T12:00:00.000Z",
  "data": {
    "inbox": { "id": "…", "address": "support-bot@homingbox.net" },
    "thread_id": "…",
    "message": { "extracted_text": "…", "labels": [], "attachments": [] }
  }
}

A webhook created without events gets all message events, including message.enriched. Webhooks created before categorisation existed keep their own list: add the event with PATCH /v1/webhooks/:id or in the dashboard. message.enriched is best effort. If sending it fails after the results were saved, the results stay on the message, so an agent that must act on categories should also check ai.enriched_at when it reads mail. See Categories and risk flags.

#Verify the signature

Each POST carries X-Mailroom-Timestamp (unix seconds) and X-Mailroom-Signature = hex(HMAC-SHA256(secret, "<timestamp>.<raw body>")). Verify against the raw body, before parsing it. Both helpers reject timestamps more than 300 seconds off and compare in constant time.

import express from 'express';
import { verifyWebhook, type WebhookEvent } from 'agentboxd';

const app = express();
// The content of new mail comes with one of these.
const MAIL_EVENTS: string[] = ['message.received', 'message.enriched', 'message.released'];

// Verify against the raw body, exactly as received.
app.post('/hooks/mail', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyWebhook(
    String(req.header('X-Mailroom-Signature')),
    String(req.header('X-Mailroom-Timestamp')),
    req.body, // Buffer
    process.env.WEBHOOK_SECRET!,
  );
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8')) as WebhookEvent;
  // withheld: not screened yet, or held. A later event brings the content.
  if (MAIL_EVENTS.includes(event.type) && !event.data.message.withheld) {
    handle(event.data.message); // once per message id: event.data.message.extracted_text
  }
  res.status(204).end();
});

from flask import Flask, abort, request
from agentboxd import verify_webhook

app = Flask(__name__)
MAIL_EVENTS = {"message.received", "message.enriched", "message.released"}


@app.post("/hooks/mail")
def mail_hook():
    if not verify_webhook(
        request.headers.get("X-Mailroom-Signature"),
        request.headers.get("X-Mailroom-Timestamp"),
        request.get_data(),  # raw bytes
        WEBHOOK_SECRET,
    ):
        abort(401)
    event = request.get_json()
    # "withheld": not screened yet, or held. A later event brings the content.
    if event["type"] in MAIL_EVENTS and "withheld" not in event["data"]["message"]:
        handle(event["data"]["message"])  # once per message id
    return "", 204

New mail can reach handle up to three times: message.received, message.enriched once its check is done, and message.released for held mail a person released. In a workspace that screens agent mail, the events from before the message was screened or released have withheld and are skipped; in one that doesn’t, each of them carries the content. So make handle act once per message id, for example with a label you add when you are done.

#Rotate the secret

We store the secret encrypted and show only its last 4 characters after creation. To replace it, call POST /v1/webhooks/:id/rotate-secret (or Rotate secret in the dashboard). Deliveries are signed with the new secret from then on; the old one stops at once.

• Without downtime: choose the new secret yourself, deploy your endpoint so it accepts a signature made with either secret, then call rotate-secret with { "secret": "…" }, and remove the old secret afterwards.
• Or rotate first (a generated secret is returned once) and update your endpoint. Deliveries that fail in between are retried for about 24 hours.

#Endpoint requirements

• A public HTTPS URL, port 443 or 1024–65535, with no username or password in it.
• The hostname must resolve only to public addresses. Private, loopback, link-local and other reserved addresses (IPv4 and IPv6), names like localhost, *.local or *.internal, and single-label hosts are refused with 422 invalid_webhook_url when you create or update the webhook.
• We resolve the hostname again for every delivery and connect only to an address we checked. If it now resolves to a private address, the attempt fails with “resolves to a private or reserved address”.
• Redirects are not followed: a 3xx answer is a failed attempt. Give us the final URL.

#Retries

Any non-2xx response or a timeout (10 s) counts as a failure. We retry 8 times with exponential backoff starting at 680 s, about 24 hours in total. A delivery that falls more than 6 hours behind this schedule (your workspace has many deliveries waiting at once and its endpoints are slow) is not sent late: it is marked failed. Every delivery shows up under Recent deliveries in the dashboard and in GET /v1/webhooks/:id/deliveries, with its status code, response time and error.

#Send a delivery again

Fixed your endpoint? Press Redeliver on a row of Recent deliveries, or call POST /v1/webhooks/:id/deliveries/:deliveryId/redeliver (or POST /v1/webhooks/:id/redeliver with { "event_id": "…" }). We send the same payload again, signed with your current secret and a new X-Mailroom-Timestamp, so a check that refuses old timestamps still accepts it. It is one attempt; X-Mailroom-Delivery stays the same, so skip ids you already handled. A delivery that is still being retried can’t be sent again until it succeeds or gives up.

#No public URL?

Open the event stream: the same events over a WebSocket your agent opens. Or use messages.wait (long-poll) or the MCP server. All three work from a laptop or a job behind NAT.