Webhooks

Eventos de entrega de email

Recibe notificaciones en tiempo real sobre el estado de entrega de tus emails. Configura tu URL de webhook en el dashboard. Todos los eventos se firman con HMAC-SHA256 por seguridad.

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

Verifica siempre la firma del webhook. Genera el secret del webhook en el dashboard y úsalo para verificar las solicitudes entrantes. Calcula el HMAC sobre el cuerpo sin procesar de la solicitud, no sobre un JSON vuelto a serializar.

Inicio rápido

Un listener que verifica la firma y luego procesa el evento. Responde con un estado 2xx en cuanto se acepte el evento.

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-Signaturestringobligatorio

    Firma HMAC-SHA256 del cuerpo de la solicitud. Formato: sha256=hex_digest

Pruebas con ngrok

Expón tu listener local a internet y registra la URL generada como tu URL de webhook en el dashboard.

ngrok http 3001
# Your webhook URL:
# https://abc123.ngrok.io/webhook/email/delivery

Eventos

Cada evento es un objeto JSON con event, timestamp y un objeto data. Abre un evento para ver su payload completo y sus campos.

¿Tu endpoint falla demasiado? Consulta Listar webhooks para revisar su estado, o Reintentar todas las fallidas para volver a encolar lo que no llegó.