Solicitudes de Webhook

Cuando ocurre un evento, Emailit envía una solicitud HTTP POST a la URL de webhook que hayas configurado. Esta página describe el formato de la solicitud, las cabeceras y el comportamiento de entrega.

Formato de solicitud

Todas las solicitudes de webhook se envían como solicitudes POST con un cuerpo JSON:

• Método: POST
• Content-Type: application/json
• Tiempo límite: 30 segundos

Cabeceras

Cada solicitud de webhook incluye las siguientes cabeceras:

Cuerpo de la solicitud

El cuerpo de la solicitud contiene la carga útil del evento como JSON:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

Respuesta esperada

Tu endpoint debe devolver un código de estado 2xx (por ejemplo, 200, 201, 204) para confirmar la recepción. Cualquier otro código de estado se considera un fallo.

Política de reintentos

Si tu endpoint no responde con un código de estado 2xx dentro de 30 segundos, Emailit reintentará la entrega siguiendo este cronograma:

Después del intento 6 (7 intentos en total), el webhook se desactiva automáticamente. Puedes reactivarlo desde el panel de control de Emailit.

Orden de entrega

Los eventos de webhook se entregan casi en tiempo real, pero no se garantiza que lleguen en orden. Utiliza el event_id y las marcas de tiempo dentro de la carga útil del evento para manejar el orden en tu aplicación.

Direcciones IP

Las solicitudes de webhook se envían desde la infraestructura de Emailit. Si necesitas incluir IPs en tu lista de permitidos, contacta con soporte para obtener la lista actual de direcciones IP de salida.

Mejores prácticas

• Responde rápidamente — Procesa el webhook de forma asíncrona y devuelve un 2xx inmediatamente. Realiza el procesamiento pesado en una tarea en segundo plano.
• Maneja duplicados — Usa el event_id para eliminar eventos duplicados. El mismo evento puede entregarse más de una vez durante los reintentos.
• Verifica las firmas — Siempre valida la cabecera X-Emailit-Signature para asegurar que la solicitud proviene de Emailit. Consulta Firma de Solicitud.