---
title: Webhooks
---

## List Webhooks
**Endpoint**: `GET /agent/v0/webhooks`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `ascending` | query | boolean | No |  |
| `limit` | query | integer | No |  |
| `page_token` | query | string | No |  |

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `count` | integer | Yes | Number of items returned. |
| `limit` | integer | No | Limit of number of items returned. |
| `next_page_token` | string | No | Page token for pagination. |
| `webhooks` | array\<object\> | Yes | Ordered by `created_at` descending. |

##### Example

```json
{
  "count": 0,
  "limit": 0,
  "next_page_token": "<string>",
  "webhooks": [
    {
      "client_id": "<string>",
      "created_at": "2026-01-01T00:00:00Z",
      "enabled": true,
      "event_types": [
        "message.received"
      ],
      "inbox_ids": [
        "<string>"
      ],
      "pod_ids": [
        "<string>"
      ],
      "secret": "<string>",
      "updated_at": "2026-01-01T00:00:00Z",
      "url": "<string>",
      "webhook_id": "<string>"
    }
  ]
}
```


## Create Webhook
**Endpoint**: `POST /agent/v0/webhooks`
**Authentication**: `Authorization: Bearer <token>`
### Request Body
Content-Type: `application/json`
#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `client_id` | string | No | Client ID of webhook. |
| `event_types` | array\<`message.received` \| `message.sent` \| `message.delivered` \| `message.bounced` \| `message.complained` \| `message.rejected` \| `domain.verified`\> | Yes | Event types for which to send events. |
| `inbox_ids` | array\<string\> | No | Inboxes for which to send events. Maximum 10 per webhook. |
| `pod_ids` | array\<string\> | No | Pods for which to send events. Maximum 10 per webhook. |
| `url` | string | Yes | URL of webhook endpoint. |

#### Example

```json
{
  "client_id": "<string>",
  "event_types": [
    "message.received"
  ],
  "inbox_ids": [
    "<string>"
  ],
  "pod_ids": [
    "<string>"
  ],
  "url": "<string>"
}
```

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `client_id` | string | No | Client ID of webhook. |
| `created_at` | string | Yes | Time at which webhook was created. |
| `enabled` | boolean | Yes | Webhook is enabled. |
| `event_types` | array\<`message.received` \| `message.sent` \| `message.delivered` \| `message.bounced` \| `message.complained` \| `message.rejected` \| `domain.verified`\> | No | Event types for which to send events. |
| `inbox_ids` | array\<string\> | No | Inboxes for which to send events. Maximum 10 per webhook. |
| `pod_ids` | array\<string\> | No | Pods for which to send events. Maximum 10 per webhook. |
| `secret` | string | Yes | Secret for webhook signature verification. |
| `updated_at` | string | Yes | Time at which webhook was last updated. |
| `url` | string | Yes | URL of webhook endpoint. |
| `webhook_id` | string | Yes | ID of webhook. |

##### Example

```json
{
  "client_id": "<string>",
  "created_at": "2026-01-01T00:00:00Z",
  "enabled": true,
  "event_types": [
    "message.received"
  ],
  "inbox_ids": [
    "<string>"
  ],
  "pod_ids": [
    "<string>"
  ],
  "secret": "<string>",
  "updated_at": "2026-01-01T00:00:00Z",
  "url": "<string>",
  "webhook_id": "<string>"
}
```

#### `400`

Error response with status 400

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `errors` | object | Yes | Validation errors. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "errors": null,
  "name": "<string>"
}
```


## Get Webhook
**Endpoint**: `GET /agent/v0/webhooks/{webhook_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `webhook_id` | path | string | Yes |  |

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `client_id` | string | No | Client ID of webhook. |
| `created_at` | string | Yes | Time at which webhook was created. |
| `enabled` | boolean | Yes | Webhook is enabled. |
| `event_types` | array\<`message.received` \| `message.sent` \| `message.delivered` \| `message.bounced` \| `message.complained` \| `message.rejected` \| `domain.verified`\> | No | Event types for which to send events. |
| `inbox_ids` | array\<string\> | No | Inboxes for which to send events. Maximum 10 per webhook. |
| `pod_ids` | array\<string\> | No | Pods for which to send events. Maximum 10 per webhook. |
| `secret` | string | Yes | Secret for webhook signature verification. |
| `updated_at` | string | Yes | Time at which webhook was last updated. |
| `url` | string | Yes | URL of webhook endpoint. |
| `webhook_id` | string | Yes | ID of webhook. |

##### Example

```json
{
  "client_id": "<string>",
  "created_at": "2026-01-01T00:00:00Z",
  "enabled": true,
  "event_types": [
    "message.received"
  ],
  "inbox_ids": [
    "<string>"
  ],
  "pod_ids": [
    "<string>"
  ],
  "secret": "<string>",
  "updated_at": "2026-01-01T00:00:00Z",
  "url": "<string>",
  "webhook_id": "<string>"
}
```

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```


## Update Webhook
**Endpoint**: `PATCH /agent/v0/webhooks/{webhook_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `webhook_id` | path | string | Yes |  |

### Request Body
Content-Type: `application/json`
#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `add_inbox_ids` | array\<string\> | No | Inboxes for which to send events. Maximum 10 per webhook. |
| `add_pod_ids` | array\<string\> | No | Pods for which to send events. Maximum 10 per webhook. |
| `remove_inbox_ids` | array\<string\> | No | Inboxes for which to send events. Maximum 10 per webhook. |
| `remove_pod_ids` | array\<string\> | No | Pods for which to send events. Maximum 10 per webhook. |

#### Example

```json
{
  "add_inbox_ids": [
    "<string>"
  ],
  "add_pod_ids": [
    "<string>"
  ],
  "remove_inbox_ids": [
    "<string>"
  ],
  "remove_pod_ids": [
    "<string>"
  ]
}
```

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `client_id` | string | No | Client ID of webhook. |
| `created_at` | string | Yes | Time at which webhook was created. |
| `enabled` | boolean | Yes | Webhook is enabled. |
| `event_types` | array\<`message.received` \| `message.sent` \| `message.delivered` \| `message.bounced` \| `message.complained` \| `message.rejected` \| `domain.verified`\> | No | Event types for which to send events. |
| `inbox_ids` | array\<string\> | No | Inboxes for which to send events. Maximum 10 per webhook. |
| `pod_ids` | array\<string\> | No | Pods for which to send events. Maximum 10 per webhook. |
| `secret` | string | Yes | Secret for webhook signature verification. |
| `updated_at` | string | Yes | Time at which webhook was last updated. |
| `url` | string | Yes | URL of webhook endpoint. |
| `webhook_id` | string | Yes | ID of webhook. |

##### Example

```json
{
  "client_id": "<string>",
  "created_at": "2026-01-01T00:00:00Z",
  "enabled": true,
  "event_types": [
    "message.received"
  ],
  "inbox_ids": [
    "<string>"
  ],
  "pod_ids": [
    "<string>"
  ],
  "secret": "<string>",
  "updated_at": "2026-01-01T00:00:00Z",
  "url": "<string>",
  "webhook_id": "<string>"
}
```

#### `400`

Error response with status 400

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `errors` | object | Yes | Validation errors. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "errors": null,
  "name": "<string>"
}
```

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```


## Delete Webhook
**Endpoint**: `DELETE /agent/v0/webhooks/{webhook_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `webhook_id` | path | string | Yes |  |

### Responses

#### `200`

Successful response

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```