Webhooks API - Documentation

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

Create webhook

POST /v1/webhooks

Request body

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL
`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
`delivered`	Email accepted by recipient server
`bounced`	Email rejected
`deferred`	Temporary failure, will retry
`opened`	Recipient opened email
`clicked`	Recipient clicked link
`unsubscribed`	Recipient unsubscribed
`complained`	Marked as spam
`inbound`	Received inbound email

Example request

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

Response

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/mailingapi",
  "events": ["delivered", "bounced", "complained", "opened", "clicked"],
  "description": "Production webhook",
  "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": ["delivered", "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": ["delivered", "bounced", "complained", "opened", "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": ["delivered", "bounced"],
    "status": "paused"
  }'

Response

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/mailingapi",
  "events": ["delivered", "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": "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"
    }
  }
}

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