# mailboxes.setEventWebhook

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.

```ts
openemail.mailboxes.setEventWebhook(
  mailboxId: string,
  body: MailboxesSetEventWebhookBody,
  options?: CallOptions,
): ApiPromise<EventWebhook>
```

It calls `PUT /mailboxes/{mailboxId}/event-webhook`: [Create or replace the mailbox's event webhook](/docs/api/mailboxes/put_MailboxEventWebhookSet) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `body` | [`MailboxesSetEventWebhookBody`](#mailboxesseteventwebhookbody) | The request's body. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`EventWebhook`](/docs/sdks/typescript/types/event-webhook). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed — URL refused |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | account_required — the mailbox has no owning account, and a hook row must reference one |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | temporary_failure — the mailbox's creation (POST /identities with eventWebhook) is still installing its hook; retry after Retry-After |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### MailboxesSetEventWebhookBody

```ts
/** The body of `mailboxes.setEventWebhook`. */
type MailboxesSetEventWebhookBody = {
  /** HMAC signing secret — write-only. Omit to keep, string to set, null to clear */
  secret?: string | null
  /** HTTPS endpoint on a public host */
  url: string
}
```

It names these types of the API, each on a page of its own: [`EventWebhook`](/docs/sdks/typescript/types/event-webhook).
