Webhooks & Notifications

Webhooks allow you to receive real-time notifications when email events occur, such as deliveries, opens, and bounces. This guide explains how to set up and use webhooks with Notify.

Supported Event Types

Notify supports the following webhook event types:

Event Type	Description
`Bounce`	When an email is rejected by the recipient's mail server
`Click`	When a recipient clicks a link in the email
`Complaint`	When a recipient marks the email as spam
`Delivery`	When an email is successfully delivered to the recipient's mail server
`DeliveryDelay`	When an email delivery is temporarily delayed
`Open`	When a recipient opens the email
`Send`	When an email is sent

Setting Up Webhooks

Via Dashboard

Go to the Webhooks page in your dashboard
Click "Add Webhook"
Enter your webhook URL
Select the events you want to receive
Click "Create Webhook"

Via API

You can also manage webhooks programmatically:

curl -X POST https://notify.cx/api/public/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "webhookUrl": "https://example.com/webhook",
    "subscribedEvents": ["Delivery", "Bounce", "Open"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "webhookUrl": "https://example.com/webhook",
    "subscribedEvents": ["Delivery", "Bounce", "Open"],
    "createdAt": "2025-04-10T12:00:00Z"
  }
}

Managing Webhooks

List All Webhooks

curl -X GET https://notify.cx/api/public/v1/webhooks \
  -H "x-api-key: your_api_key"

Get Webhook Details

curl -X GET https://notify.cx/api/public/v1/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: your_api_key"

Update a Webhook

curl -X PUT https://notify.cx/api/public/v1/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "subscribedEvents": ["Delivery", "Bounce"]
  }'

Delete a Webhook

curl -X DELETE https://notify.cx/api/public/v1/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: your_api_key"

Testing Webhooks

You can test your webhook endpoint without sending a real email:

curl -X POST https://notify.cx/api/public/v1/webhooks/test \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "webhookUrl": "https://example.com/webhook",
    "eventType": "Delivery"
  }'

Webhook Payload Format

When an email event occurs, your webhook endpoint will receive a POST request with a JSON payload similar to this:

{
  "timestamp": "2025-04-10T15:30:45Z",
  "event_type": "Delivery",
  "message_id": "0102018494848484-b51e7343-6808-4a68-b2af-845feae57f8b-000000",
  "destination": "recipient@example.com",
  "raw_event_data": {
    "deliveryTimestamp": "2025-04-10T15:30:45Z",
    "deliveredRecipients": ["recipient@example.com"],
    "processingTimeMillis": 257,
    "ipAddress": "192.168.1.1",
    "userAgent": "NotifyWebhookProcessor/1.0"
  }
}

The fields in raw_event_data will vary depending on the event type.

Best Practices for Webhook Handling

Respond quickly: Return a 200 status code promptly (within 10 seconds)
Process asynchronously: Queue events for processing after acknowledging receipt
Implement retry logic: Be prepared to handle the same event multiple times
Validate signatures: Verify the authenticity of webhook requests (documentation coming soon)
Monitor failures: Set up alerts for webhook delivery failures

Webhook Limits

Free tier accounts are limited to 1 webhook
Pro tier accounts can create up to 5 webhooks
Business tier accounts have unlimited webhooks
Each webhook endpoint should respond within 10 seconds