Webhooks API

The Webhooks API lets you create, manage, and test webhook endpoints for real-time event notifications.

Create webhook

Register a new webhook endpoint.

POST /v1/webhooks

Request body

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint URL
name	string	Yes	Webhook name
events	array	Yes	Event types to receive
description	string	No	Human-readable description
secret	string	No	Custom signing secret (auto-generated if omitted)

Available events

Event	Description
message.delivered	Email accepted by recipient server
message.bounced	Email rejected
message.deferred	Temporary failure, will retry
message.opened	Recipient opened email
message.clicked	Recipient clicked link
message.unsubscribed	Recipient unsubscribed
message.complained	Marked as spam
quality.alert	Sending quality alert

Inbound email (inbound.received) is delivered via the webhook action on an inbound route, not via this subscription endpoint — it uses a separate, flat payload format. See the Webhooks guide for details.

Example request

curl -X POST https://api.mailingapi.com/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://yourapp.com/webhooks/mailingapi",
    "events": ["message.delivered", "message.bounced", "message.complained", "message.opened", "message.clicked"],
    "description": "Main production webhook endpoint"
  }'

Response

{
  "id": "wh_abc123",
  "name": "Production webhook",
  "url": "https://yourapp.com/webhooks/mailingapi",
  "events": ["message.delivered", "message.bounced", "message.complained", "message.opened", "message.clicked"],
  "description": "Main production webhook endpoint",
  "secret": "whsec_1a2b3c4d5e6f...",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Important: Save the secret — you’ll need it to verify webhook signatures.

---

List webhooks

Retrieve all webhooks for your account.

GET /v1/webhooks

Example request

curl https://api.mailingapi.com/v1/webhooks \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/webhooks/mailingapi",
      "events": ["message.delivered", "message.bounced"],
      "status": "active",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

---

Get webhook

Retrieve details of a specific webhook.

GET /v1/webhooks/{webhook_id}

Example request

curl https://api.mailingapi.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/mailingapi",
  "events": ["message.delivered", "message.bounced", "message.complained", "message.opened", "message.clicked"],
  "description": "Production webhook",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z",
  "stats": {
    "total_sent": 15420,
    "successful": 15380,
    "failed": 40,
    "last_success": "2024-01-20T15:30:00Z",
    "last_failure": "2024-01-20T14:00:00Z"
  }
}

Webhook statuses

Status	Description
active	Webhook is receiving events
paused	Temporarily disabled
failing	Multiple consecutive failures
disabled	Permanently disabled

---

Update webhook

Update webhook configuration.

PATCH /v1/webhooks/{webhook_id}

Request body

Field	Type	Description
url	string	New endpoint URL
events	array	New event list
description	string	New description
status	string	active or paused

Example request

curl -X PATCH https://api.mailingapi.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["message.delivered", "message.bounced"],
    "status": "paused"
  }'

Response

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/mailingapi",
  "events": ["message.delivered", "message.bounced"],
  "status": "paused",
  "updated_at": "2024-01-20T16:00:00Z"
}

---

Delete webhook

Remove a webhook endpoint.

DELETE /v1/webhooks/{webhook_id}

Example request

curl -X DELETE https://api.mailingapi.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content

---

Webhook payload format

All webhook payloads follow this structure:

{
  "id": "evt_1234567890",
  "type": "message.delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "message_id": "msg_abc123",
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "subject": "Your order shipped",
    "metadata": {
      "user_id": "usr_123"
    }
  }
}

The id is generated once per event and does not change between delivery attempts — use it as your idempotency key. To tell retries apart, read the X-MailingAPI-Delivery-Attempt header instead.

---

Signature verification

Verify webhook authenticity using the X-MailingAPI-Signature header:

X-MailingAPI-Signature: t=1705315800,v1=5d2a...

See Webhooks guide for implementation examples.

---

Error codes

Code	Description
invalid_url	URL must be HTTPS
invalid_events	Unknown event type
webhook_not_found	Webhook ID not found
webhook_disabled	Webhook has been disabled