Webhooks API

Create, manage, and inspect webhook endpoints and delivery history.

GET /v1/webhooks

GET/v1/webhooks

List all webhooks. Scoped keys only see webhooks for in-scope mailboxes. The secret is never included in list responses.

response — 200 OK

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://example.com/webhook",
      "mailboxId": null,
      "events": ["message.received", "message.bounced"],
      "status": "ACTIVE",
      "failureCount": 0,
      "lastTriggeredAt": "2026-03-11T12:00:00.000Z",
      "createdAt": "2026-03-11T00:00:00.000Z"
    }
  ]
}

POST /v1/webhooks

POST/v1/webhooks

Request body

Name	Type	Description
url*	string	HTTPS endpoint URL (no localhost/private IPs)
events*	string[]	Event types to subscribe to
mailboxId	string	Scope to a mailbox. Required for scoped API keys.

Available events

message.received
message.sent
message.delivered
message.bounced
message.complaint

response — 201 Created

{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://example.com/webhook",
    "events": ["message.received"],
    "status": "ACTIVE",
    "secret": "whsec_..."
  }
}

The secret is only returned on creation. Use it to verify webhook signatures.

URL validation

The URL must use HTTPS and cannot target localhost, private IP ranges (10.x, 172.16-31.x, 192.168.x), link-local addresses, or cloud metadata endpoints.

PATCH /v1/webhooks/:id

PATCH/v1/webhooks/:id

Request body

Name	Type	Description
url	string	Updated endpoint URL
events	string[]	Updated event list
status	"ACTIVE" \| "PAUSED"	Pause or reactivate

DELETE /v1/webhooks/:id

DELETE/v1/webhooks/:id

response — 200 OK

{ "deleted": true }

GET /v1/webhooks/:id/deliveries

GET/v1/webhooks/:id/deliveries

View recent delivery attempts for a webhook. Returns the last 20 deliveries, newest first. Payload and response body are excluded for security.

response — 200 OK

{
  "deliveries": [
    {
      "id": "del_abc123",
      "event": "message.received",
      "responseStatus": 200,
      "status": "DELIVERED",
      "attempts": 1,
      "nextRetryAt": null,
      "createdAt": "2026-03-11T12:00:00.000Z"
    }
  ]
}

Delivery statuses

PENDING — Awaiting delivery or retry
DELIVERED — Endpoint returned 2xx
FAILED — All retry attempts exhausted