Webhooks

Zapmail webhooks let you subscribe to account events (domains, mailboxes, subscriptions, exports, placement tests, and workspaces) and get them pushed to your own HTTPS endpoint in near real time, instead of polling the API.

💡

This is the live reference for the shipped webhooks feature. All endpoints below are mounted under /api/v2/webhooks and are scoped per-user (the API key owner) — x-workspace-key has no effect on webhook resources.

Quick start

Create an endpoint

POST /webhooks/endpoints with your url and the enabled_events you want. Save the secret from the response — it is only ever returned once.

Verify the signature

Every delivery is signed with an X-Zapmail-Signature header. Recompute the HMAC on your side and compare before trusting the payload — see Verifying signatures below.

Go live

Subscribe to the real events you care about via enabled_events

Event envelope

Field	Description
`id`	Unique event ID (`evt_` + UUIDv7). Use this to de-duplicate — delivery is at-least-once.
`type`	One of the event types listed below.
`created`	Unix timestamp (seconds) the event was generated.
`api_version`	Envelope schema version, currently `2026-07-01`.
`data`	Event-specific payload — shape varies per `type`, see Event catalog.

Delivery request headers:

Header	Value
`Content-Type`	`application/json`
`X-Zapmail-Signature`	`t=<unix_ts>,v1=<hex_hmac_sha256>` — see Verifying signatures
`User-Agent`	`Zapmail-Webhooks/1.0`

Event catalog

Fetch this list programmatically at any time via GET /webhooks/events (returns value/label/description/category for each type) — use it to populate an event picker instead of hardcoding the strings below.

Domains

domain.updated · domain.connection_status_changed

Mailboxes

mailbox.updated

Subscriptions

subscription.status_changed

Exports

export.started · export.completed · export.failed · export.reconnected

Placement Tests

placement_test.status_changed

Workspaces

workspace.status_changed · workspace.invitations

domain.updated

Fires when a domain's status, configuration, or DNS state changes. data.domainDetails is the domain record restricted to an explicit allow-list of fields (internal relations like cloudflareCredentials are never included), plus a flattened healthScore / healthErrorMessage / healthLabel and a live assignedMailboxesCount. data.previousState contains only the fields that changed.

{
  "domainDetails": {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "userId": "a1b2c3d4-0000-0000-0000-000000000002",
    "workspaceId": "a1b2c3d4-0000-0000-0000-000000000003",
    "domain": "dummy-domain.com",
    "status": "CONNECTED",
    "purchaseType": "REGISTERED",
    "serviceProvider": "GOOGLE",
    "registeredOn": "2026-01-15T00:00:00.000Z",
    "expireOn": "2027-01-15T00:00:00.000Z",
    "isWarmedUp": true,
    "healthScore": 92,
    "healthErrorMessage": null,
    "healthLabel": "Healthy",
    "assignedMailboxesCount": 5,
    "createdAt": "2026-01-15T00:05:00.000Z",
    "updatedAt": "2026-07-30T09:12:00.000Z"
  },
  "previousState": {
    "status": "PENDING"
  }
}

domain.connection_status_changed

mailbox.updated

subscription.status_changed

subscription.billing_changed

export.started

export.completed

export.failed

export.reconnected

placement_test.status_changed

workspace.status_changed

workspace.invitations

Endpoints

All paths below are relative to /api/v2/webhooks and require the standard auth headers (x-auth-zapmail required).

Method	Path	Description
GET	`/events`	List all subscribable event types with labels/descriptions/categories.
POST	`/endpoints`	Create an endpoint: `{ url, enabled_events[] }`. Response includes `secret` — shown only this once.
GET	`/endpoints`	List all endpoints owned by the caller (never includes `secret`).
PATCH	`/endpoints/:id`	Update `url` / `enabled_events` / `status` (partial, all optional). Setting `status: "active"` resets the endpoint's consecutive-failure counter.

Verifying signatures

Every delivery includes an X-Zapmail-Signature header in the form:

X-Zapmail-Signature: t=1753100000,v1=5257a869e7bfbe86...

t — the unix timestamp (seconds) the request was signed at

v1 — an HMAC-SHA256 hex digest of ${t}.${raw_request_body}, keyed with your endpoint's secret (the whsec_... value returned once from POST /endpoints)

To verify a delivery: read the raw, unparsed request body, recompute the HMAC the same way, and compare it to v1 using a constant-time comparison. Reject the request if the signatures don't match, or if t is further from the current time than you're comfortable with (recommended: 5 minutes) to guard against replay.

Node.js

Python

PHP

cURL / OpenSSL

Delivery behavior

Timeout: 10 seconds per attempt.

Retry schedule: on failure (non-2xx response, timeout, or network error), retries follow a fixed backoff: 1m → 5m → 30m → 2h → 5h → 10h → 24h, for 8 attempts total including the first.

Redirects: not followed — your endpoint must respond directly.

Auto-disable: an endpoint's status flips to disabled after 20 consecutive failed deliveries (across all events, tracked at the endpoint level), and the owner is notified by email. Re-enable it with PATCH /endpoints/:id (status: "active"), which also resets the failure counter.

Consumer checklist

Verify X-Zapmail-Signature on every request — see Verifying signatures.

Return a 2xx as soon as the payload is durably queued; do the actual processing asynchronously rather than inline in the request handler, since slow handlers count toward the 10s timeout.

Persist the raw payload before processing, so failed processing can be replayed without needing resend.

Was this page helpful?

Quick start#

Event envelope#

Event catalog#

Endpoints#

Verifying signatures#

Delivery behavior#

Consumer checklist#

#