Saltar al contenido

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.

GPor

Presentamos Webhooks v2

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

email.accepted

Aceptado para su entrega

email.scheduled

Programado para entregarse más adelante

email.delivered

Entregado al servidor de correo del destinatario

email.bounced

Falló de forma permanente (rebote duro)

email.attempted

Fallo temporal de entrega

email.failed

Falló por un error concreto

email.rejected

Aceptado y luego rechazado

email.suppressed

El destinatario está en la lista de direcciones bloqueadas

email.received

Se aceptó un email entrante

email.complained

Queja de spam registrada

email.clicked

Se hizo clic en un enlace del email

email.loaded

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 hexadecimal
  • X-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

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

Buenas prácticas

  • Responde rápido — Devuelve un 2xx de 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_id para descartar duplicados.
  • Verifica las firmas — Valida siempre la cabecera X-Emailit-Signature para confirmar que la petición procede de Emailit.
  • Protégete frente a ataques de repetición — Comprueba X-Emailit-Timestamp y 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:

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.

Compartir

Prueba lo que acabas de leer.

3000 emails al mes gratis. Sin tarjeta de crédito.

3000 emails al mes gratis · Sin tarjeta de crédito