openemail webhooks

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 <n> stops after that many items.

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.

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.

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.

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.

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.

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.

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 <n> stops after that many items.

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.

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.

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 <n> stops after that many items.

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 <name> 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 <n> stops after that many items.

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 <name> 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 <n> stops after that many items.

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.

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.