/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}AuthCreate or replace the per-domain webhook override. Returns the plaintext signing secret ONCE — store it now. Deprecated: use `/webhooks/endpoints` instead. Responses carry `Deprecation: true` and `Sunset: Fri, 15 Jan 2027 00:00:00 GMT`; after 2027-01-15 this route returns 410. The slot is an ordinary endpoint (`legacy_slot` set) in `GET /webhooks/endpoints`.
Path parameters
workspace_id*string · uuidId of the workspace.
domain_id*string · uuidId of the domain.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.
Request body
url*string · uriDestination URL. Must be absolute https:// with a public TLD.
Example: "https://api.acme.com/webhooks/mail"
event_types*arrayEvents the destination subscribes to: any name of the catalogue (`email.*`, `domain.*`, `suppression.*`; see `/webhooks/endpoints`), or a pre-042 `message.*` alias (`message.sent|delivered|deferred|bounced|complained|failed`, kept for one release), which is delivered under the alias name. Email events carry the message; `domain.*` events carry `data: { id, fqdn, status, health }`, where `health` is `ok | degraded | failing` (drift on a verified domain; `failing` = still broken 72 h later, sends refused). `domain.created` adds `intent` and `created_at`; `domain.verified` adds `verified_at`; `domain.updated` adds `changes: [{ purpose, from, to }]` (a record purpose such as `dkim`, `mx`, `mail_from_mx`, `dmarc` with its state `missing | mismatch | conflict | propagating | verified`, or `ses` / `ses_mail_from` with the signing / MAIL FROM check status) and fires only on a real change; `domain.deleted` is sent after the domain is removed.
Example: ["email.sent","email.bounced"]
Response · 200
id*string · uuidworkspace_id*string · uuiddomain_id*string · uuidNull for the workspace-default config; set for a per-domain override.
url*string · urievent_types*arraysigning_secret_hint*stringLast 4 chars of the active signing secret.
prev_signing_secret_active*booleanTrue while a previous signing secret is still being honoured (24h grace after rotation).
prev_signing_secret_expires_at*string · date-timedisabled_at*string · date-timeSet when auto-disabled after sustained failure.
disabled_reason*stringconsecutive_failures*numbercreated_at*string · date-timeupdated_at*string · date-timesigning_secret*stringPlaintext signing secret. Returned once on create / rotate; never reconstructable.
Example
Request
PUT https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"url": "https://api.acme.com/webhooks/mail",
"event_types": [
"email.sent",
"email.bounced"
]
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"workspace_id": "00000000-0000-0000-0000-000000000000",
"domain_id": "00000000-0000-0000-0000-000000000000",
"url": "string",
"event_types": [
"string"
],
"signing_secret_hint": "string",
"prev_signing_secret_active": false,
"prev_signing_secret_expires_at": "2026-01-01T00:00:00.000Z",
"disabled_at": "2026-01-01T00:00:00.000Z",
"disabled_reason": "string",
"consecutive_failures": 0,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"signing_secret": "string"
}