Descripción general
Webhooks
Recibe notificaciones HTTP firmadas cuando los emails se entregan, rebotan, se abren o reciben clics, llegan a tu dominio de entrada o cuando cambian tus recursos.
Los webhooks envían los eventos de Emailit a tu aplicación en el momento en que ocurren, así que no tienes que consultar la API cada cierto tiempo. Úsalos para actualizar el estado de entrega en tu base de datos, dejar de enviar emails a las direcciones que rebotan o generan quejas, reaccionar a aperturas y clics, procesar el email entrante o sincronizar contactos y direcciones bloqueadas.
Cómo funciona
- Registras un endpoint. Crea un webhook con un nombre y una URL HTTPS en el panel o con la API. Emailit genera un secreto de firma para él.
- Ocurre algo. Emailit registra un evento, por ejemplo
email.delivered, y lo pone en cola para cada webhook activado que esté suscrito a ese tipo de evento y cuyo filtro de payload coincida. - Emailit envía un lote. En cuestión de segundos, Emailit envía una petición
POSTcuyo cuerpo es un array JSON de hasta 100 eventos en cola, del más antiguo al más reciente. Las peticiones a un mismo webhook se envían de una en una. - Tu endpoint responde. Cualquier código de estado
2xxen menos de 30 segundos marca todos los eventos del lote como entregados. Cualquier otra respuesta, incluidos un tiempo de espera agotado o una redirección, es un fallo, y el lote se reintenta durante unos tres días.
Cada petición incluye estas cabeceras:
| Cabecera | Valor |
|---|---|
Content-Type |
application/json |
User-Agent |
Emailit-Webhooks/2.0 |
X-Emailit-Signature |
HMAC-SHA256 en hexadecimal de {timestamp}.{raw body}, con el secreto del webhook como clave. |
X-Emailit-Timestamp |
Hora Unix, en segundos, del momento en que se firmó la petición. |
Consulta Peticiones de webhook para ver el formato completo y Firma de las peticiones para ver el código de verificación.
Ejemplo rápido
Este controlador de Express verifica la firma y después procesa cada evento del lote:
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Emailit-Timestamp') ?? '';
const signature = req.get('X-Emailit-Signature') ?? '';
const expected = crypto
.createHmac('sha256', process.env.EMAILIT_WEBHOOK_SECRET) // whsec_...
.update(`${timestamp}.`)
.update(req.body)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const a = Buffer.from(signature);
const b = Buffer.from(expected);
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
if (!fresh || !valid) return res.status(401).send('Invalid signature');
for (const event of JSON.parse(req.body)) {
switch (event.type) {
case 'email.delivered':
console.log(`Delivered ${event.data.object.id} to ${event.data.object.to}`);
break;
case 'email.bounced':
case 'email.complained':
console.log(`Stop sending to ${event.data.object.to}`);
break;
}
}
res.sendStatus(200);
});
app.listen(3000);A qué puedes suscribirte
Los webhooks cubren la entrega de emails y la interacción (email.delivered, email.bounced, email.clicked y otros), el correo entrante (email.received) y los cambios en dominios, listas de contactos, suscriptores, contactos, segmentos con seguimiento, plantillas, direcciones bloqueadas, verificaciones de email y campañas. Un webhook nuevo creado en el panel recibe todos los eventos; más adelante puedes limitarlo a tipos concretos. Consulta Tipos de eventos.
En los planes Pro, Business y Custom, un filtro de payload puede limitar un webhook a los eventos que cumplan unas reglas, por ejemplo solo los emails dirigidos a un dominio.
Límites
| Pay as you go | Pro | Business | Custom | |
|---|---|---|---|---|
| Endpoints de webhook | 3 | 10 | 100 | Flexible |
| Filtros de payload de webhook | — | Hasta 25 reglas | Hasta 25 reglas | Hasta 25 reglas |
La página de webhooks muestra cuántos endpoints estás usando, por ejemplo 2/3 used. Cuando alcanzas el límite, el botón Add webhook se desactiva hasta que elimines uno o cambies a un plan superior. Cada webhook puede enviar como máximo 5 eventos de prueba por minuto.