Postmark webhooks
Last verified against Postmark's documentation on September 27, 2026.
Postmark sends webhooks for what happens to the email you send: deliveries, bounces, spam complaints, opens, clicks, and subscription changes, plus inbound email. Postmark’s delivery rules are strict. It retries for under an hour, it drops an event for good if your handler answers with most 4xx codes, and it pauses an event type entirely if an endpoint keeps failing. Postmark also doesn’t sign webhooks, so securing them is up to you. This page covers what Postmark sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Postmark sends webhooks for
| Webhook | RecordType | Typical use |
|---|---|---|
| Delivery | Delivery | Confirm a receipt or password reset reached the recipient’s server |
| Bounce | Bounce | Mark addresses inactive and ask users to fix typos |
| Spam complaint | SpamComplaint | Suppress complainers immediately |
| Open | Open | Track engagement |
| Click | Click | Track link clicks |
| Subscription change | SubscriptionChange | Sync unsubscribes |
| Inbound | Inbound message JSON | Process incoming email |
Each server can have up to 10 webhooks with any combination of events. Inbound webhooks are configured per inbound message stream and run on separate infrastructure.
How Postmark delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with a JSON body |
| Authentication | No signature. Optional HTTP Basic Auth, and up to 30 custom headers per webhook |
| Verification check | When you create or edit a webhook, Postmark tests each event type and expects a 200 |
| Retried | 5xx, 408, 429, and network failures or timeouts |
| Dropped | Any other 4xx (for example 400, 401, 403, 404, 422). Not retried |
| Redirects | Followed, up to 10 hops |
| Retry schedule | 1 minute, 5 minutes, 10 minutes, 10 minutes, 10 minutes, then 15 minutes, about 51 minutes in total |
| Retries remaining | X-PM-Retries-Remaining header |
| Persistent failures | The failing event type is marked unverified and paused until you verify again |
| Deduplication | The X-PM-Webhook-Trace-Id header, which stays the same across retries. MessageID identifies the email, so combine it with RecordType |
| Source IPs | Published by Postmark. The origin IP can change between attempts |
Common Postmark webhook errors and how to fix them
Events silently missing
If your handler returns a 4xx other than 408 or 429, Postmark drops the event with no retry. A 401 from a misconfigured auth check, or a 422 from strict payload validation, loses the event for good. Only return 4xx for requests you truly want discarded, and return 5xx when you want Postmark to try again.
An event type stopped arriving
Postmark pauses an event type that keeps failing, and it stays paused until you fix the endpoint and verify the webhook again, in the app, through the API, or with the verify endpoint. Other event types keep working, which makes a paused type easy to miss.
Bounces lost during an outage
Postmark’s retries end about 51 minutes after the first failure. A deploy that breaks your handler for an hour, or an outage over lunch, loses every bounce and complaint in that window. Postmark has no way to resend them afterward.
Basic Auth failing
Postmark sends the username and password you configured as a standard Authorization: Basic header. If a proxy or load balancer sits in front of your handler, make sure it passes that header through.
Duplicate events
Retries, and timeouts where your handler finished but responded too late, deliver the same event again. Store the X-PM-Webhook-Trace-Id and skip repeats.
Timeouts
Postmark retries timed-out requests, so a slow handler causes duplicates. Respond with 200 first and do the work from a queue.
Why use HookDeploy with Postmark
No more dropped events
HookDeploy captures every Postmark webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Postmark sees a 200, so nothing is dropped, retried, or paused on its side. What happens next is between HookDeploy and your handler: if your code returns a 401 or a 500, the event is still in HookDeploy, ready to retry or replay.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose, which can run for hours. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured events for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
No more paused event types
Postmark pauses an event type after persistent failures. Because HookDeploy always answers Postmark with a 200, your event types stay verified even while your own server is down.
One webhook, many systems
Send each bounce to your app, your CRM, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Process inbound email privately
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so inbound email can reach an internal service with no public endpoint.
Know the limits
- Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Postmark retries for about 51 minutes before giving up. Paid plans keep accepting traffic past the included volume. - Tokens in the URL. The endpoint token sits in the webhook URL, visible to anyone with access to your Postmark webhook settings.
Securing Postmark webhooks through HookDeploy
With HookDeploy in the middle, there are two connections to secure.
Postmark to HookDeploy. Add HookDeploy’s endpoint token to the webhook URL as ?token=, and HookDeploy rejects requests without it before they’re captured. HookDeploy removes the token before forwarding, so your handler never receives it. You can also add Postmark’s webhook IPs to the endpoint’s IP allowlist on the Security tab, under Network. Endpoint tokens and IP allowlists are available on Starter and above.
HookDeploy to your handler. Don’t reuse Postmark’s Basic Auth credentials for this hop. HookDeploy redacts the Authorization header from stored requests, and retries and replays are sent from the stored copy, so those credentials wouldn’t be on them. Instead, inject your own Authorization header on the destination and check that. HookDeploy adds it to every forward, every retry, incident replays, and manual replays you send to that destination.
Set up Postmark with HookDeploy
- In HookDeploy, create an endpoint (for example,
Postmark events) and copy its URL. - On the endpoint’s Security tab, under Token, generate an endpoint token (Starter and above).
- On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery. Add a header
Authorization: Bearer YOUR_HANDLER_SECRET, and set the destination’s retries. - In Postmark, open your server’s Webhooks settings and add a webhook. Use your HookDeploy URL with
?token=YOUR_ENDPOINT_TOKENadded, choose your events, and verify the webhook. - Use Postmark’s Send test, and confirm the event appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const expectedAuth = Buffer.from(`Bearer ${process.env.HANDLER_SECRET}`);
app.post('/webhooks/postmark', express.json(), async (req, res) => {
// Check the header HookDeploy injects on every forward, retry, and destination replay.
const received = Buffer.from(req.get('authorization') ?? '');
const valid =
received.length === expectedAuth.length &&
crypto.timingSafeEqual(received, expectedAuth);
if (!valid) return res.status(401).send('Unauthorized');
const event = req.body;
if (!event.RecordType || !event.MessageID) return res.status(400).send('Unexpected payload');
res.sendStatus(200);
await enqueue({ traceId: req.get('x-pm-webhook-trace-id'), type: event.RecordType, event });
// Deduplicate on traceId in your worker.
});
FAQ
Does Postmark sign its webhooks?
No. Postmark doesn't support HMAC webhook signatures. It recommends HTTP Basic Auth combined with allowlisting its webhook IP addresses, and you can also add up to 30 custom headers to each webhook.
Why did Postmark stop retrying a webhook?
Postmark only retries 5xx errors, 408, 429, and network failures. Any other 4xx, such as a 400 or 401 from your handler, is treated as permanent and the event is dropped. Retries that do happen run for about 51 minutes in total.
Why did Postmark pause one of my webhook event types?
If an endpoint fails persistently across many events, Postmark marks that event type unverified and pauses delivery for it until you fix the endpoint and verify the webhook again. Other event types keep flowing.
How do I deduplicate Postmark webhooks?
Use the X-PM-Webhook-Trace-Id header, which stays the same across retries of the same event. The payload's MessageID identifies the email, so a delivery and a bounce for the same email share it; combine it with RecordType if you use it.
Why do HookDeploy retries fail my Basic Auth check?
HookDeploy redacts the Authorization header from stored requests, and retries and replays are sent from the stored copy. Authenticate HookDeploy's deliveries with a header you inject on the destination instead. HookDeploy adds it to every forward and retry, and to replays sent to that destination.
What does HookDeploy add to Postmark webhooks?
HookDeploy responds to Postmark right away and keeps every event, so a handler outage or a 4xx from your code no longer means a dropped bounce. You get retries, incident replay, and retention from 7 to 365 days depending on plan.