Mail API reference

Mail API · Outbound-Webhooks

patch/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Auth

Change a webhook endpoint: URL, description, events, on/off.

Only the fields sent change. `enabled: true` (or a new URL) also clears an automatic disable. Switching off cancels queued retries. The secret is unchanged; rotate it with `POST …/rotate-secret`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

endpoint_id*string · uuid

Id of the endpoint.

Headers

Idempotency-Keystring

Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`.

Request body

urlstring · uri

A new absolute https:// URL on a public host.

Example: "https://api.acme.com/webhooks"

descriptionstring

A new label; null clears it.

Example: "Production receiver"

event_typesarray

Replaces the subscription. Event types from `GET …/webhooks/event-types`. Empty or omitted means every event, including types added later. Older names (`message.sent`, `message.delivered`, `message.deferred`, `message.bounced`, `message.complained`, `message.failed`) are still accepted; an endpoint subscribed under one receives the event with that name as its `type`.

Example: ["email.sent","email.delivered"]

enabledboolean

Switch it on or off. Switching on also clears an automatic disable.

Example: true

eventsarray

Replaces the subscription. Older name for `event_types`, accepted and returned until the legacy webhook routes are retired (Sunset: 2027-01-15). Send one of the two.

domain_idstring · uuid

Domain filter; null removes it. Not allowed on a legacy slot (its domain is what makes it one).

Response · 200

id*string · uuid

The endpoint's id.

scope_type*string

What owns the endpoint: `workspace`, `app` or `community`.

Example: "workspace"

scope_id*string

Id of the owning workspace, app or community.

url*string · uri

Where events are sent.

Example: "https://api.acme.com/webhooks"

description*string

A label for people; null when unset.

Example: "Production receiver"

event_types*array

Subscribed event types. Empty means every event, including types added later.

Example: []

enabled*boolean

The on/off switch (`PATCH … { enabled }`).

status*object

`enabled` receives events. `disabled` was switched off. `auto_disabled` was switched off after 20 failed deliveries in a row or 24 hours of failures; `PATCH { enabled: true }` turns it back on.

disabled_at*string · date-time

When it was switched off; null while enabled.

disabled_reason*object

`manual`: switched off by a caller. `failing`: switched off automatically after failed deliveries. Null while enabled.

consecutive_failures*number

Failed automatic deliveries in a row; a success resets it.

first_failure_at*string · date-time

Start of the current failure streak.

signing_secret_hint*string

Last 4 characters of the signing secret.

Example: "x9Q="

prev_signing_secret_active*boolean

True while the previous secret still signs too (after a rotation, for its grace period).

prev_signing_secret_expires_at*string · date-time

Until then the previous secret signs too (after a rotation).

legacy_signature*boolean

True for endpoints carried over from the product's previous webhook system: they also receive the old signature header until its sunset date.

created_at*string · date-time

When the endpoint was created.

updated_at*string · date-time

When the endpoint last changed.

events*array

Same as `event_types`. Older name for `event_types`, accepted and returned until the legacy webhook routes are retired (Sunset: 2027-01-15). Send one of the two.

Example: ["email.delivered"]

domain_id*string · uuid

Only events about this domain; null for every event of the workspace.

legacy_slot*object

Set on the rows behind the deprecated routes: `default` (`/webhooks/default`) and `domain` (`/webhooks/domains/{id}`, which receives its domain's events instead of the default). Null for an endpoint created here.

Example

Request

PATCH https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "https://api.acme.com/webhooks",
  "description": "Production receiver",
  "event_types": [
    "email.sent",
    "email.delivered"
  ],
  "enabled": true,
  "events": [
    "email.sent"
  ],
  "domain_id": "00000000-0000-0000-0000-000000000000"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "scope_type": "workspace",
  "scope_id": "string",
  "url": "https://api.acme.com/webhooks",
  "description": "Production receiver",
  "event_types": [],
  "enabled": false,
  "status": {},
  "disabled_at": "2026-01-01T00:00:00.000Z",
  "disabled_reason": {},
  "consecutive_failures": 0,
  "first_failure_at": "2026-01-01T00:00:00.000Z",
  "signing_secret_hint": "x9Q=",
  "prev_signing_secret_active": false,
  "prev_signing_secret_expires_at": "2026-01-01T00:00:00.000Z",
  "legacy_signature": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "events": [
    "email.delivered"
  ],
  "domain_id": "00000000-0000-0000-0000-000000000000",
  "legacy_slot": {}
}