---
title: "Register a webhook on a mailbox"
method: POST
path: "/v1/mailboxes/{mailbox_id}/webhooks"
tags: ["webhooks"]
---

# Register a webhook on a mailbox

`POST /v1/mailboxes/{mailbox_id}/webhooks`

## Request

- Base URL: `https://mbag.ai/api`
- URL: `https://mbag.ai/api/v1/mailboxes/{mailbox_id}/webhooks`
- Auth: HTTP bearer

`events` defaults to `["email.received"]` when omitted. The response
includes the HMAC `secret` — this is the ONLY time it's returned;
`GET .../webhooks` never includes it.

## Path parameters

- `mailbox_id` integer, required

## Request body

- object
  - `events` string[]: Defaults to `["email.received"]` when omitted.
  - `url` string, required: Must start with `http://` or `https://`.

## Response `200`

Webhook registered.

- WebhookRecord: Returned once, on registration — this is the only response that includes `secret`.
  - `created_at` string, date-time, required
  - `customer_id` integer, required
  - `events` string[], required
  - `id` integer, required
  - `is_active` boolean, required
  - `mailbox_id` integer, required
  - `secret` string, required: HMAC secret for verifying the `X-Mailbuttons-Signature` header on delivered webhooks.
  - `url` string, required

## Other responses

- `400`: Missing or invalid `url` (empty, or doesn't start with `http://`/`https://`). Plain-text body.
- `401`: Missing or invalid credential, raised by the `ApiKeyAuth` extractor (`backend/src/api_keys.rs`) before the handler runs: no `Authorization` header, a non-`Bearer` scheme, a key that doesn't hash-match any row, or a key whose status isn't `active`. A header that isn't valid UTF-8, has no scheme token, or has `Bearer` with no key value returns 400 with this same JSON shape instead of 401.
- `404`: Mailbox not found (or not owned by the caller). Plain-text body.
- `500`: Database error. Plain-text body.

---

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