Webhooks

Creating a Webhook

POST /v0/webhooks
{
  "url": "https://your-app.com/webhook",
  "event_types": ["message.received"]
}

Event Types

message.received — New inbound email (currently emitted)
message.sent — Outbound lifecycle event (contracted, delivery rollout pending)
message.bounced — Delivery failure event (contracted, delivery rollout pending)

Webhook Payload

{
  "type": "event",
  "event_type": "message.received",
  "event_id": "evt_...",
  "message": {
    "message_id": "msg_...",
    "inbox_id": "agent@your-org.agentry.to",
    "thread_id": "thread_...",
    "from": "sender@example.com",
    "subject": "Re: Hello",
    "text": "...",
    "size": 1234,
    "created_at": "2026-03-23T12:34:56.000Z",
    "updated_at": "2026-03-23T12:34:56.000Z"
  },
  "thread": {
    "thread_id": "thread_...",
    "inbox_id": "agent@your-org.agentry.to",
    "last_message_id": "msg_...",
    "message_count": 2,
    "size": 4321,
    "created_at": "2026-03-23T12:34:56.000Z",
    "updated_at": "2026-03-23T12:34:56.000Z"
  }
}

Security

Each webhook has a secret field. Use it to verify webhook signatures in your endpoint.

Agentry webhook deliveries are signed with Svix. Every delivery includes:

svix-id
svix-timestamp
svix-signature

Verify against the raw request body before any JSON parsing.

import { Webhook } from "svix";

const secret = process.env.AGENTMAIL_WEBHOOK_SECRET!;

export function verifyWebhook(rawBody: Buffer, headers: Record<string, string>) {
	const wh = new Webhook(secret);
	return wh.verify(rawBody, headers);
}

Scope Management

You can update webhook subscriptions with:

add_inbox_ids / remove_inbox_ids
add_pod_ids / remove_pod_ids

on PATCH /v0/webhooks/{webhook_id}.