Email Center webhooks: receiving delivery, bounce and complaint events in your system

The short answer: save an HTTPS address with PUT /v1/email/webhook and choose the events: email.sent, email.delivered, email.bounced, email.complained and email.failed. For every event, for every recipient, we send a signed notice. This webhook is separate from the SMS webhook.

Saving the webhook

curl -X PUT https://api.mozout.com/v1/email/webhook \
-H "Authorization: Bearer prod_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://yourcompany.com/webhooks/email",
"events": ["email.delivered", "email.bounced", "email.complained"]}'

The answer includes the secret (secret) used to check the signature. It is only shown when the webhook is created or when you ask for a new one with "rotate_secret": true: store it on your server straight away.

What reaches your address

A JSON POST, on port 443, one call per event and per recipient, only for events after the webhook was saved:

{"event": "email.bounced", "created_at": "...",
"data": {"id": "5120", "event_id": "...", "recipient": "ana@example.com",
"detail": "...", "from": "...", "subject": "...", "simulated": false}}

Checking the signature

1	Read the header X-Webhook-Signature: t=<unix time>,v1=<hex>.

2	Compute the HMAC-SHA256 of t + "." + body, using the raw body exactly as it arrived and your secret.

3	Compare it with v1. If it does not match, reject the notice.

4	Answer 2xx within 5 seconds. Handle the event afterwards, in a queue of your own.

A step-by-step PHP example is in receiving a webhook in PHP and checking its signature.

If your server fails

Without a 2xx answer within 5 seconds, we try again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Use the event_id so you never handle the same event twice.

Operation	What for
GET /v1/email/webhook	See the address, the events, the last delivery and the last error
POST /v1/email/webhook/test	Send a signed webhook.test event now and see what your server answered
DELETE /v1/email/webhook	Stop receiving notices

Do not trust an unsigned notice. Anyone can POST to your address. Without checking v1, someone could mark e-mails as delivered or suppress customers in your system.

New to webhooks? Start with what a webhook is and webhook or polling.

Want your system to know on its own what happened to every e-mail? See the API page.

See the API page

Categories

Categories