https://api.zapmail.ai/api/v3.url and the enabled_events you want. The endpoint starts active.secret, a string starting with whsec_. It is returned only by this call. List and Get never include it, and it does not change when you update the endpoint. Store it in your secrets manager now. If you lose it, delete the endpoint and create a new one.X-Zapmail-Signature on every request. See Verify signatures.POST /webhooks/endpoints/{id}/test to queue a test.ping event, then read the result with GET /webhooks/deliveries.Internal server error, not a 4xx. Treat any 500 from these two calls as a URL problem first.| Action | Request |
|---|---|
| List event types | List Webhook Event Types: GET /webhooks/events |
| Create | Create Webhook Endpoint: POST /webhooks/endpoints |
| List | List Webhook Endpoints: GET /webhooks/endpoints (not paginated) |
| Get | GET /webhooks/endpoints/{id} |
| Update | Update Webhook Endpoint: PATCH /webhooks/endpoints/{id} |
| Delete | DELETE /webhooks/endpoints/{id} |
| Send a test event | POST /webhooks/endpoints/{id}/test |
| List deliveries | GET /webhooks/deliveries |
| Resend a delivery | POST /webhooks/deliveries/{id}/resend |
PATCH accepts url, enabled_events and status (active or disabled). Send only what changes. enabled_events replaces the whole list and must contain at least one value. Setting status to active also resets the consecutive-failure counter.DELETE removes the endpoint and its secret, drops queued retries, and keeps the delivery history.GET /webhooks/events instead of hardcoding it. test.ping is not in that list and cannot be subscribed to.POST with a JSON body in this envelope.| Field | Description |
|---|---|
id | Event ID, evt_ followed by a UUIDv7. Generated once per event, not per attempt. |
type | Event type, for example mailbox.updated. |
created | Unix timestamp in seconds when the event was generated. |
api_version | Envelope version, currently 2026-07-01. |
data | Holds one key, object, with the event payload. Its shape depends on type. |
{
"id": "evt_0197d3a1-6c52-7f1e-9b0a-4a2d8c7e1b35",
"type": "export.completed",
"created": 1792999000,
"api_version": "2026-07-01",
"data": {
"object": {
"export_id": "9b1e6f3c-2d4a-4c8e-a7b5-1f0e3d6c8a92",
"workspace_id": "a1b2c3d4-0000-0000-0000-000000000003",
"app_name": "Instantly",
"export_status": "COMPLETED",
"mailboxes": [
{
"mailbox_id": "a1b2c3d4-0000-0000-0000-000000000002",
"domain": "example.com",
"username": "john",
"first_name": "John",
"last_name": "Doe"
}
]
}
}
}| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Zapmail-Webhooks/1.0 |
X-Zapmail-Signature | t=<unix seconds>,v1=<hex> |
| Type | Fires when | data.object |
|---|---|---|
domain.updated | A domain's status, configuration or DNS state changes. | domainDetails (allow-listed domain fields, including id, domain, status, workspaceId, serviceProvider, assignedMailboxesCount, health fields) and previousState (changed fields with their old values). |
domain.connection_status_changed | A step of the domain connection process completes or fails. | id, domain, status, nameservers, expected_nameservers, next_retry_on, failure_reason. |
mailbox.updated | A mailbox's status or configuration changes. | mailboxDetails (allow-listed mailbox fields, including id, workspaceId, username, status, domain, serviceProvider, twoFactorEnabled; no password or secrets) and previousState. |
subscription.status_changed | A subscription's status changes. | id, workspace_id, subscription_id, subscription_table, previous_status, status, subscription_type, billing_cycle, period_start, period_end. |
subscription.billing_changed | A subscription's billing details change. | id, workspace_id, subscription_id, changes (each changed field as { previous, current }). |
export.started | An export job starts. | export_id, workspace_id, app_name, export_status, mailboxes. |
export.completed | An export job completes. | Same as export.started, export_status COMPLETED. |
export.failed | An export job fails. | Same, export_status FAILED, plus error. |
export.reconnected | An export reconnects after a failure. | Same, export_status RECONNECTED. |
placement_test.status_changed | A Deliverability Test's status changes. | id, previous_status, status. |
workspace.status_changed | A workspace is archived, unarchived or deleted. | id, name, previous_status, status. |
workspace.invitations | A member accepts an invite, leaves, is removed, or has their role changed. | workspace_id, action (invite_accepted, member_left, role_changed or member_removed), and, depending on the action, member_user_id, member_email, previous_role, new_role. |
email.filter_matched | An incoming email matches one of your email filter rules. | filter_id, filter_name, filter_tag, workspace_id, account, service_provider, matched_criteria, applied_actions, email, matched_at. |
test.ping | You call the test endpoint. Cannot be subscribed to. | message: Test event from Zapmail. |
subscription.status_changed: subscription_table is one of USER, DNS_SHIELD, ZAP_CARE, PLACEMENT_TEST, AI_INSIGHT, PRE_WARMED_UP. workspace_id is null for subscriptions that are not tied to a workspace, such as ZapShield (DNS_SHIELD).export.*: export_id is an internal export identifier. It is not the numeric exportId used by GET /exports/status, so you cannot correlate the two. Use workspace_id, app_name and the mailbox list to match an event to your request.domain.updated and mailbox.updated: previousState contains only the fields that changed. serviceProvider is GOOGLE, MICROSOFT or null.workspace.invitations: the action value determines which optional fields are present.domain.updated:{
"domainDetails": {
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"workspaceId": "a1b2c3d4-0000-0000-0000-000000000003",
"domain": "example.com",
"status": "CONNECTED",
"serviceProvider": "GOOGLE",
"healthScore": 92,
"healthLabel": "Healthy",
"assignedMailboxesCount": 5
},
"previousState": { "status": "PENDING" }
}domain.connection_status_changed:{
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"domain": "example.com",
"status": "NS_NOT_CHANGED",
"nameservers": ["ns1.registrar.com", "ns2.registrar.com"],
"expected_nameservers": ["ns1.zapmail.com", "ns2.zapmail.com"],
"next_retry_on": "2026-10-27T12:00:00.000Z",
"failure_reason": "Ensure your Zapmail NS records are updated at your domain registrar."
}X-Zapmail-Signature: t=1792999000,v1=5257a869e7bfbe86...t is the Unix time in seconds when the attempt was signed. It is regenerated on every attempt, so retries and resends carry a fresh t.v1 is the hex-encoded HMAC-SHA256 of the string <t>.<raw request body>, keyed with the endpoint secret (the whole whsec_... string).t and v1.t, a dot, and the raw body, using the secret as the key, and hex-encode it.v1 with a constant-time comparison.t is close to the current time.express.raw({ type: 'application/json' }) for the webhook route.t differs from your clock by more than 5 minutes (300 seconds), and de-duplicating on the envelope id. This is a recommendation, not a requirement.id.disabled and the account owner is emailed. Any successful attempt resets the counter. Test events never count toward it.disabled endpoint receives nothing. Re-enable it with PATCH /webhooks/endpoints/{id} and { "status": "active" }.GET /webhooks/deliveries lists deliveries newest first, one row per event and endpoint, showing the most recent attempt. Filter with endpoint_id, status (succeeded or failed) and event_type, and page with page and limit. The response is { deliveries, total }.payload that was sent, attempt_number, response_code, error and the first 10,000 characters of your response_body. The row id identifies the latest attempt. test.ping deliveries are listed but cannot be selected with event_type.POST /webhooks/deliveries/{id}/resend queues another attempt of an earlier event to the same endpoint with the original payload (same event id) and a new signature timestamp. The call returns once the attempt is queued, and the result appears as the next attempt_number. If the endpoint is disabled, the attempt is queued but never sent. If the endpoint was deleted, the call returns 404.id before processing, and ignore event IDs you have already handled.disabled status on your endpoints.