/v1/workspaces/{workspace_id}/webhooks/endpointsAuthAdd a webhook endpoint. Returns its signing secret once.
Deliveries are signed with the Standard Webhooks headers `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<body>">`); the returned `whsec_…` secret works unchanged with any Standard Webhooks library. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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
url*string · uriWhere to send events: an absolute https:// URL on a public host.
Example: "https://api.acme.com/webhooks"
descriptionstringA label for people.
Example: "Production receiver"
event_typesarrayEvent 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"]
enabledbooleanSend `false` to create it switched off.
Example: true
eventsarrayOlder 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","email.bounced"]
domain_idstring · uuidOnly events about this domain. Omit or null for every event of the workspace.
Example: null
Response · 201
id*string · uuidThe endpoint's id.
scope_type*stringWhat owns the endpoint: `workspace`, `app` or `community`.
Example: "workspace"
scope_id*stringId of the owning workspace, app or community.
url*string · uriWhere events are sent.
Example: "https://api.acme.com/webhooks"
description*stringA label for people; null when unset.
Example: "Production receiver"
event_types*arraySubscribed event types. Empty means every event, including types added later.
Example: []
enabled*booleanThe 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-timeWhen 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*numberFailed automatic deliveries in a row; a success resets it.
first_failure_at*string · date-timeStart of the current failure streak.
signing_secret_hint*stringLast 4 characters of the signing secret.
Example: "x9Q="
prev_signing_secret_active*booleanTrue while the previous secret still signs too (after a rotation, for its grace period).
prev_signing_secret_expires_at*string · date-timeUntil then the previous secret signs too (after a rotation).
legacy_signature*booleanTrue 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-timeWhen the endpoint was created.
updated_at*string · date-timeWhen the endpoint last changed.
events*arraySame 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 · uuidOnly events about this domain; null for every event of the workspace.
legacy_slot*objectSet 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.
signing_secret*stringThe signing secret, shown once: pass it unchanged to any Standard Webhooks verifier. Store it now; it cannot be shown again.
Example: "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
Example
Request
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/webhooks/endpoints
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.delivered",
"email.bounced"
],
"domain_id": null
}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": {},
"signing_secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}