Anuncios5 min de lectura
Presentamos Webhooks v2
Webhooks v2 ya está aquí: 36 tipos de eventos, firmas HMAC-SHA256, reintentos automáticos y documentación completa de cada payload.
GPorGeorge

Lanzamos Webhooks v2, una renovación completa de la forma en que Emailit envía notificaciones de eventos en tiempo real a tus aplicaciones. Con 36 tipos de eventos repartidos en 9 categorías de recursos, verificación de firmas criptográficas y una sólida política de reintentos, Webhooks v2 te ofrece todo lo que necesitas para crear integraciones fiables basadas en eventos.
Novedades
36 tipos de eventos en 9 recursos
Webhooks v2 abarca todos los recursos de Emailit. Puedes suscribirte exactamente a los eventos que te interesan o usar all_events para recibirlos todos.
Los eventos de email siguen todo el ciclo de vida de la entrega:
Evento | Descripción |
|---|---|
| Aceptado para su entrega |
| Programado para entregarse más adelante |
| Entregado al servidor de correo del destinatario |
| Falló de forma permanente (rebote duro) |
| Fallo temporal de entrega |
| Falló por un error concreto |
| Aceptado y luego rechazado |
| El destinatario está en la lista de direcciones bloqueadas |
| Se aceptó un email entrante |
| Queja de spam registrada |
| Se hizo clic en un enlace del email |
| Se cargó el contenido del email (apertura) |
Eventos CRUD para dominios, listas de contactos, suscriptores, contactos, plantillas, direcciones bloqueadas, verificaciones de emails y listas de verificación de emails, cada uno con sus eventos .created, .updated y .deleted.
Estructura de eventos uniforme
Cada payload de webhook sigue la misma estructura, lo que facilita crear un único manejador para todos los eventos:
{
"event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
"type": "email.delivered",
"data": {
"object": {
"id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
"object": "email",
...
}
}
}event_id identifica de forma única cada evento, type te indica qué ha ocurrido y data.object contiene el recurso completo tal como estaba en el momento del evento.
Verificación de firma HMAC-SHA256
Cada petición de webhook se firma con HMAC-SHA256 usando el secreto de tu webhook. La firma se calcula sobre {timestamp}.{rawBody}, así que puedes comprobar tanto la autenticidad como la vigencia de la petición en un solo paso.
Cada petición incluye dos cabeceras:
X-Emailit-Signature— el digest HMAC-SHA256 en hexadecimalX-Emailit-Timestamp— la marca de tiempo Unix usada en la firma
Te recomendamos encarecidamente usar una comparación en tiempo constante (p. ej., crypto.timingSafeEqual en Node.js) para evitar ataques de temporización, y rechazar las peticiones con marcas de tiempo de hace más de unos minutos para protegerte frente a ataques de repetición.
En la documentación de firma de peticiones tienes ejemplos completos de verificación en Node.js, Python, PHP, Ruby y Go.
Reintentos automáticos con retroceso exponencial
Si tu endpoint no responde con un 2xx en 30 segundos, Emailit vuelve a intentarlo automáticamente:
Intento | Espera |
|---|---|
0 | 5 segundos |
1 | 5 minutos |
2 | 30 minutos |
3 | 2 horas |
4 | 5 horas |
5 | 10 horas |
6 | 24 horas |
En total son 7 intentos a lo largo de unas 41 horas. Tras el último intento, el webhook se desactiva automáticamente. Puedes volver a activarlo desde el panel en cualquier momento.
Formato de las peticiones
Todas las peticiones de webhook son POST con un cuerpo JSON. Cada petición incluye estas cabeceras:
Cabecera | Descripción |
|---|---|
|
|
|
|
| Firma HMAC-SHA256 |
| Marca de tiempo Unix usada en la firma |
Buenas prácticas
- Responde rápido — Devuelve un
2xxde inmediato y procesa el payload de forma asíncrona en una tarea en segundo plano. - Gestiona los duplicados — El mismo evento puede entregarse más de una vez durante los reintentos. Usa
event_idpara descartar duplicados. - Verifica las firmas — Valida siempre la cabecera
X-Emailit-Signaturepara confirmar que la petición procede de Emailit. - Protégete frente a ataques de repetición — Comprueba
X-Emailit-Timestampy rechaza las peticiones con más de unos minutos de antigüedad.
Documentación completa
Hemos publicado la documentación completa de Webhooks v2, con ejemplos detallados de payloads y descripciones de los campos de los 36 eventos:
- Introducción — Descripción general y cómo funcionan los webhooks
- Tipos de eventos — Lista completa de los 36 tipos de eventos
- Peticiones de webhook — Formato de las peticiones, cabeceras y política de reintentos
- Firma de peticiones — Verificación de firmas con ejemplos de código en 5 lenguajes
Empieza ya
Consulta la documentación de webhooks para empezar o ve directamente a la referencia de la API para crear tu primer endpoint de webhook.


