Skip to content
Emitlo Docs

Webhooks API

Webhooks let your application receive real-time notifications when email events occur.

Required permission: admin

List webhooks

GET /api/v1/webhooks

Terminal window
curl https://api.emitlo.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Create webhook

POST /api/v1/webhooks

Terminal window
curl -X POST https://api.emitlo.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/emitlo",
    "event_types": ["delivered", "bounced", "complained", "opened", "clicked"]
  }'
FieldTypeRequiredDescription
urlstring✅HTTPS endpoint that will receive events
event_typesarray✅Events to subscribe to (see Webhook Events)

Response (201):

{
  "status": "success",
  "data": {
    "webhook": {
      "id": 1,
      "url": "https://yourapp.com/webhooks/emitlo",
      "event_types": ["delivered", "bounced", "complained"],
      "created_at": "2026-01-10T09:00:00Z"
    }
  }
}

Delete webhook

DELETE /api/v1/webhooks/{id}

Terminal window
curl -X DELETE https://api.emitlo.com/api/v1/webhooks/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook payload

Every event is delivered as a POST request to your endpoint with a JSON body:

{
  "event_type": "delivered",
  "timestamp": "2026-04-20T14:30:00Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "subject": "Your order is confirmed"
  }
}

Signature verification

Every request includes an X-Emitlo-Signature header for authenticity verification:

X-Emitlo-Signature: sha256=<hmac-sha256-hex>
X-Emitlo-Event: delivered
X-Emitlo-Delivery-Id: <uuid>

Verify the signature by computing HMAC-SHA256(payload, webhook_secret) and comparing it to the header value.

See Webhooks Guide for signature verification examples and retry behavior.