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.

POSThttps://your-server.com/webhook/email/delivery
!

Sempre 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ório

    Assinatura 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/delivery

Eventos

Todo evento é um objeto JSON com event, timestamp e um objeto data. Abra um evento para ver o payload completo e os campos.

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.