--- title: "openemail webhooks" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/webhooks" area: "CLI" category: "Reference" --- # openemail webhooks Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail webhooks list` List the webhook endpoints in the workspace ```bash openemail webhooks list [flags] ``` Resolves one page of the webhook endpoints registered on the key's workspace, newest first. Signing secrets are never part of a read. Only `create` and `rotateSecret` return `secret`, so a lost secret cannot be recovered from here. An endpoint subscribed to every event, which is what an endpoint created without `eventTypes` is, reports `eventTypes` as `['*']` rather than an empty array. Read `enabled`, `disabledReason` and `consecutiveFailures` as the health summary. An endpoint the server switched off after 100 consecutive failed deliveries shows `enabled: false` with `disabledAt` and a reason, while one you disabled yourself through `update` has both of those null. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `webhooks:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail webhooks list ``` Walk every page and stop after 100 items ```bash openemail webhooks list --all --max 100 ``` One JSON object per line when piped ```bash openemail webhooks list --all > webhooks.ndjson ``` Also available in: API [`GET /webhooks`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks); SDK [`webhooks.list()`](https://openemail.uk/docs/sdk/reference/webhooks#list). ### `openemail webhooks get` Read one webhook endpoint by id ```bash openemail webhooks get [flags] ``` Resolves a single endpoint with its URL, subscription list, enabled state and delivery health. The signing secret is never part of a read. It appears only in the responses of `create` and `rotateSecret`, and a lost one is replaced with `rotateSecret` rather than read back. An id from another workspace answers exactly like one that never existed, with 404 `resource_not_found`, so a 404 does not tell you whether the endpoint was deleted or was never yours. `consecutiveFailures` resets to 0 on any successful delivery and when `update` sets `enabled` to true. When it reaches 100 the server disables the endpoint, fills in `disabledAt` and `disabledReason`, and emails the workspace owner and every member whose role can read webhooks. - Scopes: `webhooks:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Examples** ```bash openemail webhooks get whe_3f9c2a7b1e4d8f60a5c7b92d ``` Print the raw JSON ```bash openemail webhooks get whe_3f9c2a7b1e4d8f60a5c7b92d --json ``` Also available in: API [`GET /webhooks/{id}`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-id); SDK [`webhooks.get()`](https://openemail.uk/docs/sdk/reference/webhooks#get). ### `openemail webhooks create` Register an HTTPS endpoint for mailbox events ```bash openemail webhooks create --url [flags] openemail webhooks create --data [flags] ``` Registers a receiver URL and subscribes it to events on the key's workspace. The endpoint starts enabled, so the next matching event is delivered to it straight away. Leave `--event-types` out, or pass an empty array, and the endpoint receives the default set, which is the `email.*` events other than `email.replied`. Every family outside it has to be named: `email.replied`, `domain.*`, `suppression.*`, `file.*` and `form.*`. Reads report an unnamed subscription as `['*']`. By default an endpoint hears about every address the workspace owns. `--address-allowlist` and `--domain-allowlist` narrow it, exactly as the same two lists narrow an API key: name whole domains, single addresses, or both. An event reaches the endpoint when the address or domain it concerns is covered. Events that name no address at all, such as `suppression.removed`, reach every endpoint whatever its lists say. `form.*` is the exception: a sign-up belongs to the whole workspace, so an endpoint limited to some addresses or domains never receives `form.submitted` or `form.confirmed`. This response is the only place the full `secret` ever appears. Every later read omits it, so store it before doing anything else, and if it is lost call `rotateSecret`. The secret is `whsec_` followed by 43 base64url characters, and the HMAC key is the whole string including the prefix, so pass it to `verifyWebhookSignature` exactly as returned. `url` must be https. `localhost`, hosts ending `.localhost`, `.internal` or `.local`, and IP literals in loopback, private, link local, carrier grade NAT, multicast or unique local ranges are refused with 422 `invalid_webhook_url`. The host is resolved again on every delivery, and an attempt to a name that resolves into one of those ranges is recorded as failed without being sent. Deliveries never follow redirects, so register the final address. - Scopes: `webhooks:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--url `: The https receiver URL. Another scheme or a blocked host is 422 `invalid_webhook_url`. Stored in normalised form, so the `url` read back can differ cosmetically. Required, here or in `--data`. - `--event-types ` (repeatable): Events to subscribe to. Omit it, or send `[]`, for the default `email.*` set: `email.received`, `email.sent`, `email.failed`, `email.cancelled`, `email.scheduled`, `email.queued`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.suppressed`, `email.opened`, `email.clicked` and `email.downloaded`. `email.replied`, `domain.verified`, `domain.sending_changed`, `domain.deleted`, `suppression.added`, `suppression.removed`, `file.uploaded`, `file.deleted`, `form.submitted` and `form.confirmed` are outside that set and have to be named. - `--description `: Free text note, at most 200 characters. - `--address-allowlist ` (repeatable): Single addresses this endpoint hears about. An event is delivered when the address it concerns is on this list, or when its domain is in `--domain-allowlist`. Leave both empty and the endpoint hears about every address the workspace owns. At most 50, and an address this workspace does not own is 422 `invalid_parameter`. - `--domain-allowlist ` (repeatable): Whole domains this endpoint hears about, including addresses added to them later. A domain also carries its own `domain.*` events. At most 25. An address whose domain is already listed here is dropped from `--address-allowlist` when the endpoint is saved, so the two lists never overlap. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail webhooks create --url https://hooks.acme.com/openemail ``` With optional flags ```bash openemail webhooks create --url https://hooks.acme.com/openemail --event-types email.received,email.bounced,email.complained --description 'Support desk sync' ``` Read the whole body from a JSON file ```bash openemail webhooks create --data @webhook.json ``` Also available in: API [`POST /webhooks`](https://openemail.uk/docs/api/reference/webhooks#post-webhooks); SDK [`webhooks.create()`](https://openemail.uk/docs/sdk/reference/webhooks#create). ### `openemail webhooks update` Change an endpoint URL, events or enabled state ```bash openemail webhooks update [flags] ``` Patches the URL, subscription list, description or enabled flag of one endpoint. Every field is optional, and an empty patch is accepted and changes nothing you can read back. A new `url` goes through the same https and host checks as `create`, and `description: null` clears the note. `--event-types` replaces the subscription set wholesale, so send the complete list you want rather than a delta. An empty array does not unsubscribe: it puts the endpoint back on the default `email.*` set. To stop deliveries, set `enabled` to false instead. `--address-allowlist` and `--domain-allowlist` replace the endpoint's scope the same way, wholesale rather than as a delta. Send both empty to widen it back to every address the workspace owns. Each list is checked against the domains and addresses this workspace actually owns, and an unknown one is 422 `invalid_parameter`. Writing `enabled` clears `disabledAt` and `disabledReason` either way, so an endpoint you switch off yourself reports both as null. Setting it back to true also resets `consecutiveFailures` to 0, which is how an endpoint the server disabled after 100 failures is brought back. Events that fire while an endpoint is disabled are never delivered to it later, but a delivery that failed before it was switched off can be sent again with `replayDelivery` once it is back on, one event at a time. - Scopes: `webhooks:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Flags** - `--url `: Replacement https URL, checked against the same host rules as `create`. - `--event-types ` (repeatable): Complete replacement subscription set. `[]` means the default `email.*` set. - `--address-allowlist ` (repeatable): Complete replacement list of single addresses this endpoint hears about. At most 50. Send `[]` on both lists to hear about every address again. - `--domain-allowlist ` (repeatable): Complete replacement list of whole domains this endpoint hears about, including addresses added to them later. At most 25. - `--description `: Replacement note of at most 200 characters, or null to clear it. - `--enabled`: False stops deliveries. True resumes them and resets `consecutiveFailures`. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail webhooks update whe_3f9c2a7b1e4d8f60a5c7b92d --event-types email.sent,email.bounced,email.complained --enabled ``` Print the raw JSON ```bash openemail webhooks update whe_3f9c2a7b1e4d8f60a5c7b92d --event-types email.sent,email.bounced,email.complained --enabled --json ``` Also available in: API [`PATCH /webhooks/{id}`](https://openemail.uk/docs/api/reference/webhooks#patch-webhooks-id); SDK [`webhooks.update()`](https://openemail.uk/docs/sdk/reference/webhooks#update). ### `openemail webhooks delete` Delete an endpoint and its delivery log ```bash openemail webhooks delete [flags] ``` Removes the endpoint for good. Deliveries stop immediately, the signing secret is gone, and the delivery log for the endpoint is deleted with it, so read it with `listAllDeliveries` first if you need it for an audit trail. There is no undo and no soft delete. If the aim is only to pause deliveries, call `update` with `enabled: false` and keep the endpoint, its secret and its log. The response is a tombstone rather than an empty body, so a log line can name what went. Deleting frees a slot against the workspace's endpoint limit straight away. - Scopes: `webhooks:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Examples** ```bash openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d ``` Skip the confirmation, for scripts ```bash openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --yes ``` Also available in: API [`DELETE /webhooks/{id}`](https://openemail.uk/docs/api/reference/webhooks#delete-webhooks-id); SDK [`webhooks.delete()`](https://openemail.uk/docs/sdk/reference/webhooks#delete). ### `openemail webhooks rotate-secret` Issue a new signing secret for an endpoint ```bash openemail webhooks rotate-secret [flags] ``` Generates a new signing secret and resolves with the endpoint plus the new plaintext `secret`. As with `create`, this response is the only place that secret appears, so store it before anything else. There is no overlap window. Every delivery is signed at send time with the current secret, so the old one stops verifying the moment this call commits, and any event that fires before your receiver has the new secret fails verification on your side. The safe order is to deploy a receiver that tries both the old secret and a new one read from config, call this, write the returned secret to config, then drop the old one. `test` confirms the new secret verifies before you remove the fallback. - Scopes: `webhooks:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Examples** ```bash openemail webhooks rotate-secret whe_3f9c2a7b1e4d8f60a5c7b92d ``` Skip the confirmation, for scripts ```bash openemail webhooks rotate-secret whe_3f9c2a7b1e4d8f60a5c7b92d --yes ``` Also available in: API [`POST /webhooks/{id}/rotate-secret`](https://openemail.uk/docs/api/reference/webhooks#post-webhooks-id-rotate-secret); SDK [`webhooks.rotateSecret()`](https://openemail.uk/docs/sdk/reference/webhooks#rotateSecret). ### `openemail webhooks test` Send a synthetic event and report how delivery went ```bash openemail webhooks test [flags] ``` Posts a signed synthetic `email.sent` event to the endpoint and waits for the attempt to finish before resolving. The payload `data` is `{ test: true, note }` and no mail is sent, so it is safe against a production receiver. It proves the URL is reachable and that your signature check accepts the current secret before real mail depends on it. The outcome comes back as `delivery`, read from the newest row of the delivery log. `status` is `delivered` for any 2xx answer and `failed` otherwise, `responseCode` is the HTTP status or null when no response arrived, such as a DNS failure or the 5 second timeout, and `error` explains a failure. A 3xx counts as failed because redirects are never followed. The event goes out whatever the endpoint subscribes to, and even when it is disabled. It is recorded like any delivery, so it appears in `listDeliveries` and can be sent again with `replayDelivery`, but it is tried once and leaves `consecutiveFailures` and `lastDeliveryAt` alone, so a failing test never counts toward the 100 that disable an endpoint. A 410 Gone answer does switch the endpoint off, as it would for a real event. - Scopes: `webhooks:write`. - Needs a sign-in. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Examples** ```bash openemail webhooks test whe_3f9c2a7b1e4d8f60a5c7b92d ``` Print the raw JSON ```bash openemail webhooks test whe_3f9c2a7b1e4d8f60a5c7b92d --json ``` Also available in: API [`POST /webhooks/{id}/test`](https://openemail.uk/docs/api/reference/webhooks#post-webhooks-id-test); SDK [`webhooks.test()`](https://openemail.uk/docs/sdk/reference/webhooks#test). ### `openemail webhooks list-deliveries` List one page of delivery attempts for one endpoint ```bash openemail webhooks list-deliveries [flags] ``` Returns one page of an endpoint's delivery log, newest first. `status`, `since` and `until` narrow it the way the Deliveries tab of the app does: `status: 'failed'` is its "only failed" switch. Each attempt is one POST with a 5 second timeout, and one event can appear several times: when the failure is worth repeating, a delivery is tried up to 8 times, as it happens and then after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, about 27 and a half hours in all, and each `replayDelivery` adds a row of its own. `attempt` and `maxAttempts` say which try a row is, and `eventId` is the same across all of them, so this log distinguishes a retry from a new event. `nextAttemptAt` is when the automatic retry that follows a row is due, and null when none is waiting, so a failed row with a time in it is not the final word. `status` is `delivered` for a 2xx answer and `failed` for anything else, including a 3xx, since redirects are not followed. `responseCode` null means no response arrived, such as a DNS or TLS failure or the timeout, which is a different fact from a receiver that answered. `durationMs` is null only when the attempt was never made because the server could not read the signing secret, and `error` then says so. The body that was sent and your server's answer are not part of this response, and `getDelivery` returns both. `listWorkspaceDeliveries` reads every endpoint at once. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `webhooks:read`. - Needs a sign-in. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Flags** - `--status `: `failed` keeps only the attempts that did not get a 2xx, the "only failed" view of the app; `delivered` keeps the rest. - `--since `: Only rows at or after this instant. A `Date` is sent as ISO 8601, and a string must already be one. - `--until `: Only rows before this instant. It has to be later than `since`, or the server answers 400 `invalid_parameter`. - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, passed back unchanged. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail webhooks list-deliveries whe_3f9c2a7b1e4d8f60a5c7b92d ``` With optional flags ```bash openemail webhooks list-deliveries whe_3f9c2a7b1e4d8f60a5c7b92d --status failed --limit 50 ``` Walk every page and stop after 100 items ```bash openemail webhooks list-deliveries whe_3f9c2a7b1e4d8f60a5c7b92d --all --max 100 ``` One JSON object per line when piped ```bash openemail webhooks list-deliveries whe_3f9c2a7b1e4d8f60a5c7b92d --all > webhooks.ndjson ``` Also available in: API [`GET /webhooks/{id}/deliveries`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-id-deliveries); SDK [`webhooks.listDeliveries()`](https://openemail.uk/docs/sdk/reference/webhooks#listDeliveries). ### `openemail webhooks get-delivery` Read one delivery attempt in full, with the body that was sent ```bash openemail webhooks get-delivery [flags] ``` Resolves one attempt from an endpoint's delivery log with what `listDeliveries` leaves out. `payload` is the exact JSON body that was POSTed, `{ id, type, createdAt, data }`, and `responseBody` is the first 2,000 characters your server answered, or null when nothing came back or the answer was a redirect. `attempts` lists every try of the same event on this endpoint, oldest first: the first attempt, the automatic retries and any replays, each with its own `id`, `attempt`, `status`, `responseCode`, `error` and `createdAt`. They share `eventId`, which is the payload `id` your receiver saw. `nextAttemptAt` is when the next automatic retry of the event is due, whichever attempt it follows, and null when none is waiting. `replayRefusal` says whether `replayDelivery` would accept this attempt before you call it: null when it would, and otherwise the `code` and `message` the replay would be refused with, such as `webhook_disabled` while the endpoint is switched off, or `retry_in_progress` while an automatic retry of the same event is being sent. - Scopes: `webhooks:read`. - Needs a sign-in. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. - `` (required): Delivery id, `whd_` followed by 24 hex characters, as `listDeliveries` returns it. **Examples** ```bash openemail webhooks get-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 ``` Print the raw JSON ```bash openemail webhooks get-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 --json ``` Also available in: API [`GET /webhooks/{id}/deliveries/{deliveryId}`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-id-deliveries-deliveryid); SDK [`webhooks.getDelivery()`](https://openemail.uk/docs/sdk/reference/webhooks#getDelivery). ### `openemail webhooks replay-delivery` Send one stored event to the endpoint again, now ```bash openemail webhooks replay-delivery [flags] ``` Posts the event behind a recorded attempt to the endpoint once more, straight away, and resolves when that attempt has finished. The body is the one stored with the original, with the same `id`, `type`, `createdAt` and `data`, so a receiver that drops ids it has already handled treats the replay as the event it already knows. Only `X-OpenEmail-Signature` is new, because every POST is signed with the current secret at the moment it goes out, so a replay verifies after a `rotateSecret` too. It accepts a delivered attempt as well as a failed one. Replaying a success is how a receiver that lost its copy, or handled it wrongly, is brought back in step. Any attempt of the event will do, since they all carry the same event. The replay is recorded in the log as a new delivery, attempt 1 of 1, and is never retried automatically. Before it goes out, the automatic retries of the same event that have not started are paused, so the receiver never gets two copies at once. When the replay is delivered they stay cancelled; when it fails they resume on their schedule. If an automatic retry of the event is being sent at that very moment, the replay sends nothing and is refused with 409 `retry_in_progress`, and if another replay of the same event is still being sent, it is refused with 409 `replay_in_progress`, so two copies never go out at once. The call resolves with 200 whatever your server answered, so branch on `delivery.status` rather than on whether the promise rejected. - Scopes: `webhooks:write`. - Needs a sign-in. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. - `` (required): Any attempt of the event to send again, `whd_` followed by 24 hex characters. **Examples** ```bash openemail webhooks replay-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 ``` Print the raw JSON ```bash openemail webhooks replay-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 --json ``` Also available in: API [`POST /webhooks/{id}/deliveries/{deliveryId}/replay`](https://openemail.uk/docs/api/reference/webhooks#post-webhooks-id-deliveries-deliveryid-replay); SDK [`webhooks.replayDelivery()`](https://openemail.uk/docs/sdk/reference/webhooks#replayDelivery). ### `openemail webhooks list-workspace-deliveries` List one page of delivery attempts across every endpoint ```bash openemail webhooks list-workspace-deliveries [flags] ``` Returns one page of the whole workspace's delivery log, newest first: the all-endpoints Deliveries tab of the app. Each row carries `endpointId`, so the endpoint an attempt went to is never lost. `--endpoint-ids` narrows it to some endpoints, and `status`, `since` and `until` work exactly as they do on `listDeliveries`. The body that was sent is not here: read it with `getDelivery`, passing the row's `endpointId` and `id`. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `webhooks:read`. - Needs a sign-in. **Flags** - `--endpoint-ids ` (repeatable): Endpoint ids to read, at most 50, sent comma-separated. Left out, every endpoint in the workspace. - `--status `: `failed` keeps only the attempts that did not get a 2xx, the "only failed" view of the app; `delivered` keeps the rest. - `--since `: Only rows at or after this instant. A `Date` is sent as ISO 8601, and a string must already be one. - `--until `: Only rows before this instant. It has to be later than `since`, or the server answers 400 `invalid_parameter`. - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, passed back unchanged. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail webhooks list-workspace-deliveries ``` With optional flags ```bash openemail webhooks list-workspace-deliveries --status failed --limit 50 ``` Walk every page and stop after 100 items ```bash openemail webhooks list-workspace-deliveries --all --max 100 ``` One JSON object per line when piped ```bash openemail webhooks list-workspace-deliveries --all > webhooks.ndjson ``` Also available in: API [`GET /webhooks/deliveries`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-deliveries); SDK [`webhooks.listWorkspaceDeliveries()`](https://openemail.uk/docs/sdk/reference/webhooks#listWorkspaceDeliveries). ### `openemail webhooks list-activity` List one page of what happened to one endpoint ```bash openemail webhooks list-activity [flags] ``` Returns one page of an endpoint's audit log, newest first, the Activity tab of the endpoint in the app. Every change is a row: `created`, `updated`, `enabled`, `disabled`, `auto_disabled`, `secret_rotated`, `tested`, `replayed` and `removed`, whether it came from the app, from a key over the API, or from OpenEmail itself. `actor` says who, with `label` already formatted the way the app shows it: `@username` for a person, `API key ` for a key, and `actor` is null when OpenEmail made the change on its own, such as switching an endpoint off after 100 failed events in a row. `detail` carries what moved: the URL, `previousUrl` when it changed, the event types and allowlists an update set, or the status and response code a test or a replay got. Nothing is pruned, and a removed endpoint keeps its history, so this answers for an endpoint that is gone too. `since` and `until` keep a window. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `webhooks:read`. - Needs a sign-in. **Arguments** - `` (required): Endpoint id, `whe_` followed by 24 hex characters. **Flags** - `--since `: Only rows at or after this instant. A `Date` is sent as ISO 8601, and a string must already be one. - `--until `: Only rows before this instant. It has to be later than `since`, or the server answers 400 `invalid_parameter`. - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, passed back unchanged. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail webhooks list-activity whe_3f9c2a7b1e4d8f60a5c7b92d ``` Walk every page and stop after 100 items ```bash openemail webhooks list-activity whe_3f9c2a7b1e4d8f60a5c7b92d --all --max 100 ``` One JSON object per line when piped ```bash openemail webhooks list-activity whe_3f9c2a7b1e4d8f60a5c7b92d --all > webhooks.ndjson ``` Also available in: API [`GET /webhooks/{id}/activity`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-id-activity); SDK [`webhooks.listActivity()`](https://openemail.uk/docs/sdk/reference/webhooks#listActivity). ### `openemail webhooks list-workspace-activity` List one page of what happened to every endpoint ```bash openemail webhooks list-workspace-activity [flags] ``` Returns one page of the whole workspace's webhook audit log, newest first, the Activity tab of Settings, Webhooks. Every change is a row: `created`, `updated`, `enabled`, `disabled`, `auto_disabled`, `secret_rotated`, `tested`, `replayed` and `removed`, whether it came from the app, from a key over the API, or from OpenEmail itself. `actor` says who, with `label` already formatted the way the app shows it: `@username` for a person, `API key ` for a key, and `actor` is null when OpenEmail made the change on its own, such as switching an endpoint off after 100 failed events in a row. `detail` carries what moved: the URL, `previousUrl` when it changed, the event types and allowlists an update set, or the status and response code a test or a replay got. `--endpoint-ids` narrows it to some endpoints, removed ones included, and `since` and `until` keep a window. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `webhooks:read`. - Needs a sign-in. **Flags** - `--endpoint-ids ` (repeatable): Endpoint ids to read, at most 50, sent comma-separated. Left out, every endpoint in the workspace. - `--since `: Only rows at or after this instant. A `Date` is sent as ISO 8601, and a string must already be one. - `--until `: Only rows before this instant. It has to be later than `since`, or the server answers 400 `invalid_parameter`. - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, passed back unchanged. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail webhooks list-workspace-activity ``` With optional flags ```bash openemail webhooks list-workspace-activity --since 2026-09-01T00:00:00Z ``` Walk every page and stop after 100 items ```bash openemail webhooks list-workspace-activity --all --max 100 ``` One JSON object per line when piped ```bash openemail webhooks list-workspace-activity --all > webhooks.ndjson ``` Also available in: API [`GET /webhooks/activity`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-activity); SDK [`webhooks.listWorkspaceActivity()`](https://openemail.uk/docs/sdk/reference/webhooks#listWorkspaceActivity). ### `openemail webhooks list-events` List the events an endpoint can subscribe to ```bash openemail webhooks list-events [flags] ``` Returns every event an endpoint can name in `eventTypes`, each with a sentence saying when it fires, and the limits an endpoint is held to: how many endpoints the workspace may have, which its plan decides, and how many addresses and domains one allowlist may name. An endpoint that names no events receives every email event except `email.replied`, so `email.replied` and the domain, suppression, file and form families only reach an endpoint that asks for them by name. - Scopes: `webhooks:read`. - Needs a sign-in. **Examples** ```bash openemail webhooks list-events ``` Print the raw JSON ```bash openemail webhooks list-events --json ``` Also available in: API [`GET /webhooks/events`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-events); SDK [`webhooks.listEvents()`](https://openemail.uk/docs/sdk/reference/webhooks#listEvents). ### `openemail webhooks stats` Read how webhook deliveries went inside a window ```bash openemail webhooks stats [flags] ``` Returns the numbers behind the Analytics tab of the Webhooks page: how many delivery attempts were made, how many were delivered and how many failed, the median time a receiver took to answer, a series of buckets, the events sent and the response codes received. It covers every endpoint, or the ones `--endpoint-ids` names. Each try of an event counts as one attempt, so an event retried three times counts three times. The window runs from `since` to `until`, and left out it is the 30 days before now. `grain` sets the bucket width and the key shape, `YYYY-MM-DD`, `YYYY-MM-DDTHH` or `YYYY-MM-DDTHH:MM`, and `--offset-minutes` shifts the boundaries so days break where the reader's day does. - Scopes: `webhooks:read`. - Needs a sign-in. **Flags** - `--endpoint-ids ` (repeatable): Only these endpoints, at most 50. Left out, every endpoint. - `--since `: The start of the window, a `Date` or an ISO 8601 instant. Defaults to 30 days before `until`. - `--until `: The end of the window, not included. Defaults to now. - `--grain ` (default `"day"`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`. - `--offset-minutes ` (default `0`): Minutes east of UTC to bucket in, from -840 to 840, defaulting to 0. Pass `-new Date().getTimezoneOffset()` for the local zone. **Examples** ```bash openemail webhooks stats ``` With optional flags ```bash openemail webhooks stats --grain day ``` Print the raw JSON ```bash openemail webhooks stats --json ``` Also available in: API [`GET /webhooks/stats`](https://openemail.uk/docs/api/reference/webhooks#get-webhooks-stats); SDK [`webhooks.stats()`](https://openemail.uk/docs/sdk/reference/webhooks#stats).