Webhooks : événements, signatures et nouvelles tentatives

Événements

Abonnez chaque endpoint à 1 à 20 de ces types d’événements :

• 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

Données de signature

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

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

Requête et contenu

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

Exigences pour le récepteur

• Calculez la signature à partir du corps de requête brut exact.
• Comparez les signatures à temps constant.
• Rejetez les timestamps en dehors de votre fenêtre autorisée.
• Stockez event_id et traitez chaque événement une seule fois.
• Ne présumez pas que les événements arrivent dans l'ordre du cycle de vie.

Contrôles sortants

La création d'un point de terminaison exige HTTPS. Les cibles privées, loopback, link-local, de métadonnées, porteuses d'identifiants et internes sont bloquées et re-résolues au moment de la connexion. Les redirections ne sont pas suivies. La livraison utilise des délais d'expiration et un nombre de tentatives limités.

Délais et nouvelles tentatives

Toute réponse 2xx acquitte l’événement. Un délai dépassé (15 s), une erreur réseau ou tout autre statut est un échec. Postline effectue jusqu’à 6 tentatives : la première, puis après 1 min, 5 min, 30 min, 2 h et 8 h. Chaque tentative est journalisée et toute livraison peut être rejouée manuellement via l’API ou le tableau de bord.