Product

Signed webhooks

Delivery events with HMAC signatures.

Start freeDocumentation
HMAC-SHA256
// Headers: Postline-Timestamp, Postline-Event-Id, Postline-Signature
signed   = timestamp + "\0" + event_id + "\0" + raw_body
expected = "v1=" + hex(HMAC-SHA256(webhook_secret, signed))
constant_time_compare(expected, Postline-Signature)

// 2xx acknowledges the event. Otherwise up to 6 attempts:
// now, +1m, +5m, +30m, +2h, +8h (15 s timeout each)

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

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.

Resources

Verify every delivery eventTransactional email REST APISecurity at Postline