Postmark Delivery webhook payload example

Postmark · event: Delivery (RecordType) · content type: application/json

This is a representative sample — fake IDs, real structure. To see a payload with your data, point the provider at a capture URL (button below).

See it live, not frozen

One click creates a free capture bin with this exact payload already in it — pretty-printed, headers inspectable, replayable to your own endpoint:

Then paste the bin's URL into Postmark's webhook settings to capture a real delivery. No signup.

Headers

content-type: application/json
x-pm-retries-remaining: 6
x-pm-webhook-trace-id: 3f9c2a71-58d4-4b06-9e12-c07a5d81f4b3

Body

{
  "RecordType": "Delivery",
  "MessageStream": "outbound",
  "ServerID": 23,
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "Recipient": "ada@example.com",
  "Tag": "welcome-email",
  "DeliveredAt": "2026-08-30T09:33:54.9070259Z",
  "Details": "250 2.0.0 OK  1788082434 x12-20020a05 - gsmtp",
  "Metadata": {
    "user_id": "usr_84nQz2",
    "flow": "onboarding"
  }
}

Things that bite people

There is no signature header — by design. Postmark's docs state it doesn't support HMAC signing; the recommended protection is HTTP Basic auth embedded in the webhook URL (https://user:pass@example.com/hook) plus allowlisting Postmark's published webhook IP ranges. Validate the payload shape (RecordType + MessageID present) as a further sanity check.
The Basic-auth trap: Postmark only retries 5xx, 408, 429 and network failures. Any other 4xx — including the 401 your endpoint returns when the Basic-auth password is wrong — means the event is dropped permanently, with no retry. A typo'd password silently loses every event while the dashboard shows failures piling up.
Retry schedule for retryable failures: 1 m → 5 m → 10 m → 10 m → 10 m → 15 m after the previous attempt, then that individual event is abandoned. Each request carries X-PM-Retries-Remaining so you can see where you are in the schedule. If an endpoint keeps failing across many events, Postmark pauses that event type (per-type, so a broken Bounce handler doesn't stop Delivery events) until you re-verify the webhook.
Deduplicate on X-PM-Webhook-Trace-Id — it stays stable across retries of the same event. MessageID alone is not enough: an email to three recipients is one MessageID but three separate Delivery events (one per recipient), so use MessageID + Recipient if the trace header is absent.
"Delivery" means the receiving server returned a 250 OK (that's the raw SMTP response in Details) — not that the message reached the inbox. Redirects are followed up to 10 hops (unlike GitHub, which follows none), and Metadata echoes back the custom metadata you attached when sending.

Send it yourself

Reproduce this delivery against any endpoint (your handler, a bin, staging):

$ curl -X POST https://your-endpoint.example/hook \
  -H 'content-type: application/json' \
  -H 'x-pm-retries-remaining: 6' \
  -H 'x-pm-webhook-trace-id: 3f9c2a71-58d4-4b06-9e12-c07a5d81f4b3' \
 -d '{
  "RecordType": "Delivery",
  "MessageStream": "outbound",
  "ServerID": 23,
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "Recipient": "ada@example.com",
  "Tag": "welcome-email",
  "DeliveredAt": "2026-08-30T09:33:54.9070259Z",
  "Details": "250 2.0.0 OK  1788082434 x12-20020a05 - gsmtp",
  "Metadata": {
    "user_id": "usr_84nQz2",
    "flow": "onboarding"
  }
}'

← All payload examples · Signature debugger · Docs