What Are Webhooks? (Explained)

Webhooks are one of Postmark’s most powerful features, and they come up often in customer questions.

Here’s a simple breakdown to help you understand what they are, how they work, and how we can support customers with them.

🌐 What is a Webhook?

Most important thing to understand:

A webhook lets Postmark send information to a customer’s system when specific email events happen.

Instead of customers asking Postmark for updates (polling), Postmark proactively sends them a JSON payload in real time.

A webhook is like Postmark’s way of tapping a customer’s shoulder to say, “Hey! Something just happened with your email - here are the details.” It is automatic!

Instead of the customer having to constantly check in with Postmark to ask, “Anything new?”, Postmark sends the information straight to them as soon as it happens.

Think of it like this:

Postmark delivers an email.
As soon as that happens, we notify the customer’s app about the event (bounce, delivery, open, etc.) by sending data to a webhook URL they’ve provided.

This makes it easier for customers to trigger actions in their own systems, like:
✔️ Logging a bounce in their CRM.
✔️ Triggering a workflow after an email is opened.
✔️ Creating a support ticket when they receive an inbound email.

🛠 How Do Webhooks Work in Postmark?

The customer sets up a webhook URL in their Postmark server or stream (this is where Postmark will send POST requests).
They choose which event types to enable:
- 🔗Bounce - A bounce webhook will push data to your application in an easily parsable, JSON format, as soon as Postmark processes the bounce report.
- 🔗Delivery - The Delivery webhook is a way for Postmark to notify your application that an email was successfully delivered to the receiving server.
- 🔗Open Tracking - An open webhook can instantly notify your application of message opens by POSTing the data in a JSON document to the webhook URL that you specify.
- 🔗Click Tracking - The Click webhook is a way for Postmark to notify your application that a unique recipient clicked a tracked link in your email. Postmark will POST one event per unique click to your webhook for clicks in links to messages sent within your retention period (which is 45 days by default, but the data retention period can be customized from 7 to 365 days).
- 🔗Spam Complaint - A spam complaint is recorded when a user clicks This is Spam or Mark as Spam from email clients like Yahoo, Hotmail, AOL, etc... from their inbox.
- 🔗Subscription Change - A subscription change is recorded when an email address is added or removed from a Message Stream's Suppression list.
- 🔗Inbound - The inbound webhook is a key part of processing inbound email with Postmark. It’s described in more detail in the Process Email section, but the basic premise is that Postmark will accept and parse any emails sent to your server’s unique inbound email address (found on the “Settings” page of your Inbound Message Stream)” and any emails sent to your inbound forwarding domain. Postmark will then POST the email as JSON to the URL you specify.
- 🔗SMTP API Error - SMTP API Error is an internal rejection error that Postmark will respond with when you attempt to send via SMTP to a recipient who was previously suppressed due to a Bounce, Spam Complaint, Unsubscribe or a Manual Suppression.
When an event happens, Postmark sends a POST request with a JSON payload containing details about the event.
The customer’s app receives that data and can act on it immediately.

👉 Learn more: 🔗Webhooks Overview (external doc)

✅ Webhook verification

When you create or edit a webhook, Postmark checks that your endpoint is reachable before turning it on. It sends a test request for each event type you've enabled, and every one has to return a 200 for the webhook to go live.

If a test fails, Postmark tells you which event type failed and the response it got back, and it doesn't save the webhook. You can either remove the failing event type and try again, or fix your endpoint and resubmit.

Setting up your endpoint before it's ready? You can save a webhook without testing it (it won't receive events until it passes verification), then verify it once your endpoint is live.

If a webhook that's been working starts failing consistently, Postmark marks that event type as unverified and pauses it until you fix your endpoint and verify again. This happens per event type, so a problem with one (say, bounces) won't stop the others.

👉 Learn more: Verifying your webhook

📝 Popular Customer Use Cases

Bounce Webhook: Update mailing lists to suppress bounced addresses.
Delivery Webhook: Confirm message delivery for time-sensitive emails.
Inbound Webhook: Turn incoming emails into support tickets.
Spam Complaint Webhook: Flag users who mark emails as spam.
Click/Open Tracking Webhooks: Analyze engagement in transactional emails.

🔗 What is the Webhooks API?

The Webhooks API allows customers to manage their webhooks programmatically.

With it, they can:

List all webhooks for a server or stream.
Create new webhooks.
Edit or delete existing webhooks.
Automate webhook management across multiple environments.

This is helpful for customers with complex setups or staging/production environments.

🆘 Troubleshooting Webhooks

When helping a customer with webhook issues, here’s what to check:

✅ 1. Is the webhook URL reachable?

Can you open it in a browser?
Are there firewall restrictions? (Postmark’s IP ranges may need allowlisting.)

✅ 2. Is the webhook set up correctly in Postmark?

Are the correct events enabled?
Does the customer’s app support HTTPS and authentication if used?

✅ 3. What’s the response code from the customer’s endpoint?

Your endpoint needs to return a 200 for Postmark to count the delivery as successful. If it returns something else, whether Postmark retries depends on the code: it retries on 5xx errors, 408, and 429 (temporary problems), but treats other 4xx codes like 403 or 404 as permanent and doesn't retry them.
Check your Activity feed in Postmark for webhook delivery attempts.

✅ 4. Testing the webhook

Follow our help docs to set up a webhook, and then use https://requestbin.com/ to create a public bin. This will give you a temporary public endpoint to which we can send the requests when a specific event occurs (e.g. a Delivery, or a Bounce), depending on what you need to troubleshoot. Asking a customer to test with RequestBin makes it easier to identify if the issue is maybe with the endpoint they are using.

Once you complete the test, make sure to delete your webhook.

Customers can simulate requests using Postmark’s sample payloads.

✅ 5. 500 or 403 errors when POSTing to a Webhook URL

Customers might reach out if they can see that we’re unable to send POSTs to their webhook and there’s an error such as 403 or 500. From our side, we do not have more detailed information on what the issue is. The 403 or 500 errors are coming from the customer’s server.

A 403 typically means that their URL understood the request but refused to fulfill it for some reason. A 500 error typically indicates the inbound webhook URL was down at the time we attempted delivery of the JSON for the inbound message

A couple of reasons why this might be happening and some suggestions you can offer up:

The customer can try allowlisting our IPs in case there any firewalls in place for that URL which could prevent it from receiving requests:

🔗IPs for Firewalls | Postmark Support Center
We can ask the customer if they have any logs on their end which could reveal more information. If not, can they add logging to the inbound handling code? If they can log when the URL receives a POST and the result of the URL's attempt to process it, they should be able to capture any errors so they can see what is going wrong.
If your webhook does heavy work (like handling large attachments), respond quickly with a 200 first and do the processing afterward, so a slow response doesn't get counted as a failed delivery. See Retry attempts for how retries work.

🔗A generic guide on error codes by RFC.

🗝️ Key Things to Know as Support

Webhooks are real-time and push-based - no polling required. Read: AUTOMATIC.
If your endpoint keeps failing, Postmark stops retrying after its retry schedule runs out and doesn't store the events, so it's worth setting up verification and monitoring.
Debugging often requires the customer to check their server logs.
For secure setups, they can use Basic Auth or IP filtering.
Because a failed delivery can be retried, your endpoint may occasionally get the same event twice — store each MessageID and check for it before acting so you don't process anything twice.

📚 Further Reading