Webhooks API

Create and list webhook subscriptions for delivery events.

Overview

Webhooks notify your server about email events (delivery, open, click, bounce, complaint, and more). Each subscription is authorized by one verified sending domain. By default events fire for that domain and its subdomains. Optionally set matchMode to hosts or froms to limit delivery to specific subdomains or from addresses without verifying extra domains.

Dashboard: Webhooks. Guide: Webhooks & Notifications.

Plan limits

Routes

• GET /api/webhooks — list (includes domainId, domain, matchMode, matchHosts, matchFroms)
• POST /api/webhooks — create (webhookUrl, subscribedEvents, domainId, optional matchMode / matchHosts / matchFroms)
• GET /api/webhooks/{id} — get one
• PUT /api/webhooks/{id} — update (subscribedEvents, optional domainId and match filters)
• DELETE /api/webhooks/{id} — delete
• POST /api/webhooks/test — send a test payload

Auth: x-api-key header for API calls, or a signed-in dashboard session when using the UI.

curl -X POST https://notify.cx/api/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: $NOTIFY_API_KEY" \
  -d '{
    "webhookUrl": "https://example.com/webhooks/notify",
    "subscribedEvents": ["Delivery", "Bounce", "Complaint"],
    "domainId": "123e4567-e89b-12d3-a456-426614174000",
    "matchMode": "hosts",
    "matchHosts": ["outreach.example.com"]
  }'

Response:

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "webhookUrl": "https://example.com/webhooks/notify",
    "subscribedEvents": ["Delivery", "Bounce", "Complaint"],
    "domainId": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "example.com",
    "matchMode": "hosts",
    "matchHosts": ["outreach.example.com"],
    "matchFroms": [],
    "createdAt": "2025-04-10T12:00:00Z"
  }
}

Interactive schema: /api-docs.

matchMode defaults to domain (verified parent + subdomains). hosts requires matchHosts; froms requires matchFroms. Values must be covered by the verified domain.