Webhooks: eventos, firmas y reintentos

Eventos

Suscribe cada endpoint a entre 1 y 20 de estos tipos de evento:

• email.accepted
• email.queued
• email.sent
• email.delivered
• email.deferred
• email.bounced
• email.complained
• email.opened
• email.clicked
• email.received
• email.suppressed
• domain.verified
• domain.failed

Entrada de la firma

HMAC-SHA256(secret, timestamp + "\0" + event_id + "\0" + body)

Postline-Timestamp: 1784743200
Postline-Event-Id: evt_…
Postline-Signature: v1=…

Solicitud y contenido

POST https://example.com/hooks/postline
Content-Type: application/json
Postline-Event-Id: evt_3f2a9c…
Postline-Timestamp: 1784743200
Postline-Signature: v1=5d41402abc4b2a76…

{
  "id": "evt_3f2a9c…",
  "type": "email.delivered",
  "created_at": "2026-11-05T12:00:00Z",
  "data": {
    "email_id": "msg_01J…",
    "recipient": "user@example.net",
    "provider": "gmail",
    "smtp_response": "250 2.0.0 OK"
  }
}

Requisitos del receptor

• Calcula la firma a partir del cuerpo de solicitud «crudo» exacto.
• Compara las firmas en tiempo constante.
• Rechaza timestamps fuera de tu ventana permitida.
• Guarda event_id y procesa cada evento una sola vez.
• No asumas que los eventos llegan en el orden del ciclo de vida.

Controles de salida

La creación de endpoints requiere HTTPS. Los destinos privados, loopback, link-local, de metadatos, con credenciales incrustadas e internos se bloquean y se resuelven de nuevo en el momento de la conexión. No se siguen redirecciones. La entrega usa timeouts acotados e intentos de reintento limitados.

Tiempos de espera y reintentos

Cualquier respuesta 2xx confirma el evento. Un tiempo de espera (15 s), un error de red o cualquier otro estado cuenta como fallo. Postline hace hasta 6 intentos: el primero y reintentos tras 1 min, 5 min, 30 min, 2 h y 8 h. Cada intento queda en el registro de entregas y cualquier entrega puede reenviarse manualmente desde la API o el panel.