All articles
Engineering

Webhooks: events, signatures and retries

Which events Postline sends, how to verify every request and what happens when your endpoint is down.

Events

Subscribe each endpoint to 1–20 of these event types:

  • 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

Signature input

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

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

Request and payload

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

Receiver requirements

  • Compute the signature from the exact raw request body.
  • Compare signatures in constant time.
  • Reject timestamps outside your allowed window.
  • Store event_id and process each event once.
  • Do not assume events arrive in lifecycle order.

Outbound controls

Endpoint creation requires HTTPS. Private, loopback, link-local, metadata, credential-bearing, and internal targets are blocked and resolved again at dial time. Redirects are not followed. Delivery uses bounded timeouts and retry attempts.

Timeouts and retries

Any 2xx response acknowledges the event. A timeout (15 s), a network error or any other status counts as a failure. Postline makes up to 6 attempts: the first one and retries after 1 min, 5 min, 30 min, 2 h and 8 h. Every attempt is recorded in the delivery log, and any delivery can be replayed manually through the API or dashboard.