---
title: "Create a webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create a webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.agentboxd.com`
- URL: `https://api.agentboxd.com/v1/webhooks`
- Auth: HTTP bearer

`{ url, events?, inbox_ids?, enabled?, secret?, payload?: "full" | "envelope", headers? }`. `url` must be a public HTTPS endpoint (`422 invalid_webhook_url` otherwise). `events` lists each event type at most once; repeats are dropped. `payload: "full"` sends message and draft content, so it needs the key’s `messages:read` for message and attachment events and `drafts:read` for draft events (`403 insufficient_permissions` otherwise). Without `payload`, a key that lacks them gets `envelope`. The secret is returned only here. `headers`: up to 10 extra headers sent with every delivery, e.g. `{ "Authorization": "Bearer …" }` for your own check next to the signature. Values are stored encrypted and never returned (webhooks show `header_names`); `Host`, `Content-Type` and our `X-Mailroom-*` headers can’t be set. On `PATCH`, `headers` replaces the set and `null` clears it. A workspace can have up to 20 webhooks (`409 webhook_limit_reached`); one webhook can take any number of event types and inboxes.

Permission: `webhooks:manage`.

## Request body

- object
  - `url` string, uri, required
  - `events` string[]
  - `inbox_ids` string[], nullable
  - `enabled` boolean
  - `secret` string
  - `payload` 'full' | 'envelope'
  - `headers` object

## Response `200`

OK

- object

## Other responses

- `4XX`: Error
- `5XX`: Error

---

[API](https://skmtc.dev/agentboxd/apis/agentboxd-api.md) · [All operations](https://skmtc.dev/agentboxd/apis/agentboxd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentboxd/apis/agentboxd-api/revisions/ee7b079f0e97?raw)