Webhooks
Eventos de entrega de email
Receba notificações em tempo real sobre o status de entrega dos seus emails. Configure sua URL de webhook no dashboard. Todos os eventos são assinados com HMAC-SHA256 por segurança.
https://your-server.com/webhook/email/deliverySempre verifique a assinatura do webhook. Gere o secret do webhook no dashboard e use-o para verificar as requisições recebidas. Calcule o HMAC sobre o corpo bruto da requisição, não sobre um JSON serializado de novo.
Início rápido
Um listener que verifica a assinatura e depois processa o evento. Responda com um status 2xx assim que o evento for aceito.
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
function verifySignature(rawBody, signature) {
if (!signature) return false;
const expected = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(rawBody)
.digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
// timingSafeEqual throws when the lengths differ
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// express.raw keeps the body as a Buffer, exactly as it was sent
app.post('/webhook/email/delivery', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
return res.status(401).json({ error: 'Invalid signature' });
}
const { event, emailId, data } = JSON.parse(req.body.toString('utf8'));
console.log('[Email Delivery] ' + event + ' - ' + emailId);
if (event === 'delivered') {
console.log(' Recipient: ' + data.recipientEmail);
} else if (event === 'bounced') {
console.log(' Reason: ' + data.reason);
}
res.status(200).json({ received: true });
});
app.listen(3001, () => {
console.log('Email delivery webhook listener on port 3001');
console.log(' POST /webhook/email/delivery');
});Headers
X-Webhook-SignaturestringobrigatórioAssinatura HMAC-SHA256 do corpo da requisição. Formato:
sha256=hex_digest
Testando com ngrok
Exponha seu listener local na internet e cadastre a URL gerada como sua URL de webhook no dashboard.
ngrok http 3001
# Your webhook URL:
# https://abc123.ngrok.io/webhook/email/deliveryEventos
Todo evento é um objeto JSON com event, timestamp e um objeto data. Abra um evento para ver o payload completo e os campos.
Entrega
O que acontece com um email no caminho até a caixa de entrada.
queuedEnviado uma vez quando um email entra na fila de entrega, para todo email: API, SMTP e campanhas. Enviado de novo quando o email é movido para outro IP ou servidor para uma nova tentativa.
processingEnviado quando o email passou pelas nossas verificações e está prestes a ser enviado ao servidor de destino.
deliveredEnviado quando o servidor de email de destino aceita o email.
bouncedEnviado quando um email é rejeitado de vez: o endereço não existe, o domínio não pode receber emails ou paramos de tentar.
spamEnviado quando o servidor de email de destino recusa o email como spam ou por motivo de política durante a entrega.
retryingEnviado sempre que um email ainda não pôde ser entregue e será tentado de novo.
failedEnviado quando desistimos de um email depois que as novas tentativas se esgotam.
return_pathEnviado quando uma mensagem de bounce (DSN) chega depois, após o servidor de destino ter aceitado o email. Uma falha muda o email para bounced. Um aviso de atraso ou de entrega só envia este evento.
Tracking
O que o destinatário faz depois que ele chega.
email_openedEnviado quando um destinatário abre um email com tracking de abertura ativo. Inclui o dispositivo, o IP, o país e se a abertura veio por um proxy.
email_clickedEnviado quando um destinatário clica em um link de um email com tracking de cliques ativo. Inclui a URL e se foi o primeiro clique.
unsubscribeEnviado quando um destinatário cancela a inscrição a partir de um dos seus emails: na página de descadastro, pelo botão de um clique da caixa de email dele (Gmail, Yahoo, Outlook) ou por email através do header List-Unsubscribe.
tracking_preferences_updatedEnviado quando um destinatário muda a escolha de tracking de aberturas ou cliques na página de preferências de tracking. Ele continua recebendo seus emails: isto não é um descadastro.
Seu endpoint está falhando muito? Veja Listar webhooks para conferir o status, ou Reenviar todas as falhas para recolocar na fila o que não chegou.