# Create or replace the domain's event webhook

One URL per domain, all events, no filters. Mailboxes on the domain start feeding it within seconds (a background walk arms them) — take a baseline first and treat the first batches as deltas. Any PUT re-enables, and re-runs the arm walk: it is the recovery if a walk ever died mid-domain (visible as a dead_lettered `arm:<domain>` row in the delivery log). 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/domains/{domain}/event-webhook`

### Path parameters

- `domain` (string, required) — Domain name

### 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** — Domain not found or not accessible to this principal

`application/json` → ErrorBody

**409** — account_required: the domain has no owning account, and a hook row must reference one (the legacy directory; once the partitioned directory answers, a platform domain's hook is accepted for the system caller)

`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 platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

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

## TypeScript SDK

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

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