---
title: Webhooks
description: Get notified when events occur in your inboxes.
surface: shared
---

## Creating a Webhook

```bash
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

```json
{
  "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.

```typescript
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}`.