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.
https://your-server.com/webhook/email/deliveryVerifica 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-SignaturestringobligatorioFirma 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/deliveryEventos
Cada evento es un objeto JSON con event, timestamp y un objeto data. Abre un evento para ver su payload completo y sus campos.
Entrega
Lo que le pasa a un email en su camino a la bandeja de entrada.
queuedSe envía una vez cuando un email entra en la cola de entrega, para todos los emails: API, SMTP y campañas. Se envía de nuevo cuando el email se mueve a otra IP o servidor para volver a intentarlo.
processingSe envía cuando el email pasó nuestras verificaciones y está a punto de enviarse al servidor de destino.
deliveredSe envía cuando el servidor de correo de destino acepta el email.
bouncedSe envía cuando un email se rechaza definitivamente: la dirección no existe, el dominio no puede recibir correo o dejamos de intentarlo.
spamSe envía cuando el servidor de correo de destino rechaza el email como spam o por un motivo de política durante la entrega.
retryingSe envía cada vez que un email todavía no se pudo entregar y se volverá a intentar.
failedSe envía cuando dejamos de intentar un email porque se agotaron los reintentos.
return_pathSe envía cuando un mensaje de bounce (DSN) llega más tarde, después de que el servidor de destino aceptara el email. Un fallo pasa el email a bounced. Un aviso de retraso o de entrega solo envía este evento.
Tracking
Lo que hace el destinatario cuando llega.
email_openedSe envía cuando un destinatario abre un email con el tracking de aperturas activo. Incluye el dispositivo, la IP, el país y si la apertura vino de un proxy.
email_clickedSe envía cuando un destinatario hace clic en un enlace de un email con el tracking de clics activo. Incluye la URL y si fue el primer clic.
unsubscribeSe envía cuando un destinatario se da de baja desde uno de tus emails: en la página de baja, con el botón de un clic de su buzón (Gmail, Yahoo, Outlook) o por email a través del header List-Unsubscribe.
tracking_preferences_updatedSe envía cuando un destinatario cambia su elección de tracking de aperturas o clics en la página de preferencias de tracking. Sigue recibiendo tus emails: esto no es una baja.
¿Tu endpoint falla demasiado? Consulta Listar webhooks para revisar su estado, o Reintentar todas las fallidas para volver a encolar lo que no llegó.