CamelMailer
DocsAPISDKsTemplatesHow-to

Webhooks

Get an HTTP POST for every message event (deliveries, failures, bounces, opens, clicks) instead of polling the API.

Create a webhook

Per server, in the dashboard (Server → Webhooks) or via the management API:

terminal
curl -X POST https://mail.yourdomain.com/api/v2/admin/organizations/acme/servers/production/webhooks \
  -H "X-Admin-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://app.acme.com/hooks/camelmailer" }'

Webhooks can be enabled and disabled without deleting them (POST …/webhooks/{id}/enable / …/disable), which helps during incident response.

Events

  • Delivery events: a message was accepted by the destination, deferred, or permanently failed.
  • Bounces: a bounce message came back for something you sent.
  • Engagement: opens and clicks, when tracking is enabled for the stream.

Verify the signature

Payloads are RSA-signed with the installation key, so your endpoint can prove the origin. Fetch the public key once (dashboard → server settings), then verify the signature header on every request before trusting the body.

Treat webhook handlers as untrusted input regardless: parse defensively, respond fast (2xx), and do the real work async. Failed deliveries are retried with backoff, so a slow handler creates duplicate work for itself.

Debugging

# every attempt, with request/response details, in the dashboard:
Server → Webhooks → Request log

The full walkthrough with a working receiver is in How-to: receive webhooks.