# Create or replace the mailbox's event webhook

One URL per mailbox, all events, no filters. Any PUT re-enables a hook the 24h auto-disable turned off. Omit `secret` to keep the stored one, pass a string to rotate, null to clear. What your endpoint receives (payload, `X-OpenEmail-Signature` scheme, retry policy) is specified as `event-batch` in this document's top-level `webhooks` section.

## `PUT /api/v1/mailboxes/{mailboxId}/event-webhook`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Request body (required)

`application/json`

- `url` (string <uri>, required) — HTTPS endpoint on a public host
- `secret` (string | null, 1–256 chars) — HMAC signing secret — write-only. Omit to keep, string to set, null to clear

### Responses

**200** — The hook

`application/json` → EventWebhook

- `consecutiveFailures` (integer, required) — Consecutive delivery failures; reset by any success or PUT
- `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
- `disabledReason` (string | null, required) — 'failing' after the 24h auto-disable; any PUT re-enables
- `enabled` (boolean, required)
- `failingSince` (integer | null, required) — When the current failing streak began, epoch seconds
- `hasSecret` (boolean, required) — Whether a signing secret is set (write-only)
- `lastDeliveredAt` (integer | null, required) — Last successful delivery, epoch seconds
- `lastFailure` (string | null, required)
- `lastFailureAt` (integer | null, required) — Last failed delivery, epoch seconds
- `scope` ("mailbox" | "domain", required)
- `updatedAt` (integer <int64>, required) — Last update timestamp in epoch seconds
- `url` (string, required)
- `degraded` (boolean) — Platform domains only: true while attempts above the hook's supported rate are queued on their retry ladder (never dropped). The health fields of a platform hook are a projection published at a fixed cadence of about a minute
- `domain` (string) — Present on the domain scope
- `mailboxId` (string) — Present on the mailbox scope
- `retryAfter` (integer | null) — Platform domains only: when the degraded hook has room again, epoch seconds

**400** — validation_failed — URL refused

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**409** — account_required — the mailbox has no owning account, and a hook row must reference one

`application/json` → ErrorBody

**413** — too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing

`application/json` → ErrorBody

**503** — temporary_failure — the mailbox's creation (POST /identities with eventWebhook) is still installing its hook; retry after Retry-After

`application/json` → ErrorBody

### Example request

```bash
curl -X PUT 'https://api.open.email/api/v1/mailboxes/{mailboxId}/event-webhook' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "string"
  }'
```

## TypeScript SDK

[`openemail.mailboxes.setEventWebhook`](/docs/sdks/typescript/mailboxes/set-event-webhook)

```ts
const eventWebhook = await openemail.mailboxes.setEventWebhook(mailboxId, {
  secret: 'whsec_5e8a1c9f2b7d4e6a8c1f3b5d7e9a2c4f',
  url: 'https://hooks.acme.example/openemail',
})
```
