A resposta curta: grave um endereço HTTPS com PUT /v1/email/webhook e escolha os eventos: email.sent, email.delivered, email.bounced, email.complained e email.failed. A cada evento, de cada destinatário, enviamos um aviso assinado. Este webhook é diferente do webhook do SMS.
Gravar o 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"]}'
A resposta traz o segredo (secret) para conferir a assinatura. Só se mostra quando o webhook é criado ou quando pede um novo com "rotate_secret": true: guarde-o logo no servidor.
O que chega ao seu endereço
Um POST em JSON, no porto 443, uma chamada por evento e por destinatário, só para eventos depois de o webhook ser gravado:
{"event": "email.bounced", "created_at": "...",
"data": {"id": "5120", "event_id": "...", "recipient": "ana@example.com",
"detail": "...", "from": "...", "subject": "...", "simulated": false}}
Conferir a assinatura
| 1 |
Leia o cabeçalho X-Webhook-Signature: t=<hora unix>,v1=<hex>.
|
|
| 2 |
Calcule o HMAC-SHA256 de t + "." + corpo, com o corpo tal como chegou, sem o voltar a formatar, e o seu segredo.
|
|
| 3 |
Compare com o v1. Se não bater, recuse o aviso.
|
|
| 4 |
Responda 2xx em menos de 5 segundos. Trate o evento depois, numa fila sua.
|
|
Um exemplo em PHP, passo a passo, está em receber um webhook em PHP e verificar a assinatura.
Se o seu servidor falhar
Sem uma resposta 2xx em 5 segundos, tentamos de novo ao fim de 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas. Use o event_id para não tratar o mesmo evento duas vezes.
| Operação |
Para quê |
| GET /v1/email/webhook |
Ver o endereço, os eventos, a última entrega e o último erro |
| POST /v1/email/webhook/test |
Enviar agora um evento webhook.test assinado e ver o que o seu servidor respondeu |
| DELETE /v1/email/webhook |
Deixar de receber avisos |
|
Não confie num aviso sem assinatura. Qualquer pessoa pode fazer um POST para o seu endereço. Sem conferir o v1, alguém podia marcar e-mails como entregues ou bloquear clientes no seu sistema.
|
|
Quer que o seu sistema saiba sozinho o que aconteceu a cada e-mail? Veja a página da API.
Ver a página da API
|
Português
English
