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.interweb.co.mz/v1/email/webhook \
-H "Authorization: Bearer prod_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://asuaempresa.co.mz/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.
|
|
Want your system to know on its own what happened to every e-mail? See the API page.
See the API page
|
Português
English
