Anunciamos Webhooks v2

Estamos lanzando Webhooks v2, una renovación completa de cómo Emailit entrega notificaciones de eventos en tiempo real a tus aplicaciones. Con 36 tipos de eventos distribuidos en 9 categorías de recursos, verificación de firma criptográfica y una política de reintentos robusta, Webhooks v2 te proporciona todo lo que necesitas para crear integraciones confiables 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 recibir todo.

Eventos de email que rastrean el ciclo completo de entrega:

Evento	Descripción
email.accepted	Aceptado para entrega
email.scheduled	Programado para entrega futura
email.delivered	Entregado al servidor de correo del destinatario
email.bounced	Falló permanentemente (rebote duro)
email.attempted	Fallo temporal de entrega
email.failed	Falló debido a un error específico
email.rejected	Aceptado y luego rechazado
email.suppressed	El destinatario está en la lista de supresión
email.received	Email entrante fue aceptado
email.complained	Queja de spam registrada
email.clicked	Se hizo clic en un enlace del email
email.loaded	El contenido del email fue cargado (abierto)

Eventos CRUD para dominios, audiencias, suscriptores, contactos, plantillas, supresiones, verificaciones de email y listas de verificación de email, cada uno con eventos .created, .updated y .deleted.

Estructura de eventos consistente

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",
      ...
    }
  }
}

El event_id identifica únicamente cada evento, type te indica qué ocurrió, y data.object contiene el recurso completo al momento del evento.

Verificación de firma HMAC-SHA256

Cada solicitud de webhook está firmada con tu secreto de webhook usando HMAC-SHA256. La firma se calcula sobre {timestamp}.{rawBody}, así puedes verificar tanto la autenticidad como la frescura en un solo paso.

Cada solicitud incluye dos encabezados:

• X-Emailit-Signature — el digest hexadecimal HMAC-SHA256
• X-Emailit-Timestamp — la marca de tiempo Unix usada en la firma

Recomendamos encarecidamente usar comparación segura de tiempo (ej. crypto.timingSafeEqual en Node.js) para prevenir ataques de tiempo, y rechazar solicitudes con marcas de tiempo de más de unos minutos para protegerse contra ataques de repetición.

Ejemplos completos de verificación en Node.js, Python, PHP, Ruby y Go están disponibles en la documentación de Firma de Solicitud.

Reintentos automáticos con retroceso exponencial

Si tu endpoint no responde con un 2xx dentro de 30 segundos, Emailit reintenta automáticamente:

Intento	Retraso
0	5 segundos
1	5 minutos
2	30 minutos
3	2 horas
4	5 horas
5	10 horas
6	24 horas

Son 7 intentos totales durante aproximadamente 41 horas. Después del intento final, el webhook se desactiva automáticamente. Puedes reactivarlo desde el panel en cualquier momento.

Formato de solicitud

Todas las solicitudes de webhook son POST con un cuerpo JSON. Cada solicitud incluye estos encabezados:

Encabezado	Descripción
Content-Type	application/json
User-Agent	Emailit-Webhook/1.0
X-Emailit-Signature	Firma HMAC-SHA256
X-Emailit-Timestamp	Marca de tiempo Unix usada en la firma

Mejores prácticas

• Responde rápidamente — Devuelve un 2xx inmediatamente y procesa el payload de forma asíncrona en una tarea en segundo plano.
• Maneja duplicados — El mismo evento puede entregarse más de una vez durante los reintentos. Usa event_id para eliminar duplicados.
• Verifica las firmas — Siempre valida el encabezado X-Emailit-Signature para confirmar que la solicitud proviene de Emailit.
• Protégete contra ataques de repetición — Verifica el X-Emailit-Timestamp y rechaza solicitudes de más de unos minutos.

Documentación completa

Hemos publicado documentación completa para Webhooks v2 con ejemplos detallados de payload y descripciones de campos para 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
• Solicitudes de Webhook — Formato de solicitud, encabezados y política de reintentos
• Firma de Solicitud — Verificación de firma con ejemplos de código en 5 lenguajes

Comenzar

Dirígete a la documentación de Webhooks para empezar, o ve directamente a la Referencia de API para crear tu primer endpoint de webhook.