What Are Webhooks? (Explained)

Webhooks are one of Postmark’s most powerful features. They let your systems receive updates from Postmark automatically whenever something important happens—like a bounce, delivery, or open event.

💡 What is a Webhook?

A webhook lets Postmark send information to your system in real time when specific email events occur.

Instead of having to ask Postmark for updates (a process called “polling”), Postmark proactively pushes a JSON payload to a URL you provide whenever an event happens.

Think of it like Postmark tapping your shoulder to say:

“Hey! Something just happened with your email—here are the details.”

For example:

Postmark delivers an email.
Postmark instantly notifies your app about that delivery (or bounce, open, click, etc.) by sending structured data to your webhook endpoint.
Your app can then act on that data—logging it, triggering a workflow, or sending a notification.

🛠 How Webhooks Work in Postmark

You set up a webhook URL in your Postmark server or message stream (this is where Postmark sends POST requests).
You choose which event types you’d like to receive.
Postmark sends a JSON payload to your webhook whenever those events occur.
Your application receives that data and can take action immediately.

🔔 Supported Webhook Types

Webhook type	What it does
Bounce	Sends a JSON payload when Postmark processes a bounce report.
Delivery	Notifies your app when an email is successfully delivered to the recipient’s server.
Open Tracking	Sends a payload when a recipient opens an email.
Click Tracking	Sends data when a recipient clicks a tracked link. Each unique click event generates one POST to your webhook.
Spam Complaint	Notifies you when a recipient marks your email as spam in their inbox.
Subscription Change	Alerts you when an address is added to or removed from a Message Stream’s suppression list.
Inbound	Sends JSON data for any incoming email sent to your Inbound Stream address or forwarding domain.
SMTP API Error	Reports when a message sent via SMTP was rejected due to a suppression (e.g., bounce, spam complaint, unsubscribe, or manual suppression).

👉 Learn more: Webhooks Overview

🧩 What You Can Do With Webhooks

Webhooks make it easy to automate tasks and connect Postmark with your other tools.

Use case	Example
Bounce Webhook	Update mailing lists to remove 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 Webhooks	Analyze engagement for transactional messages.

🔗 What is the Webhooks API?

The Webhooks API lets you manage your webhooks programmatically. You can:

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

This is especially useful for customers managing multiple servers or staging/production environments.
📘 Learn more: Webhooks API Reference

🧰 Troubleshooting Webhooks

If your webhook isn’t receiving events as expected, here are a few things to check:

1. ✅ Is the webhook URL reachable?

Try opening the URL in a browser.
Check for firewall restrictions—Postmark’s IPs may need to be whitelisted.
Reference: IP Addresses for Firewalls

2. ⚙️ Is it set up correctly in Postmark?

Confirm the webhook URL is entered under your Server or Stream’s Webhooks tab.
Verify that the correct event types are enabled.
Make sure your endpoint supports HTTPS and any authentication you’re using.

3. 📡 What’s the response code from your endpoint?

Postmark retries sending if the endpoint returns a 4xx or 5xx error.
Check your Activity feed in Postmark for webhook delivery attempts.

4. 🧪 Test your webhook

Use RequestBin to test whether Postmark can reach your webhook.

Create a temporary bin.
Set it as your webhook URL in Postmark.
Trigger an event (like a bounce or delivery).
Inspect the JSON payloads you receive.

This helps confirm whether the issue lies with your endpoint or configuration.

5. 🚨 Handling 403 or 500 errors

A few common reasons for these errors:

403 Forbidden: The webhook URL received the request but refused to fulfill it. Check for access restrictions, authentication, or IP blocking.
500 Internal Server Error: The customer’s webhook server was down or couldn’t process the request.

Tips:

Whitelist Postmark’s IPs if firewalls are in place.
Add logging to your webhook handler to capture and debug incoming POSTs.
If your webhook handles large attachments, ensure it can accept large POSTs or completes within Postmark’s 2-minute timeout.

Reference: HTTP Status Codes (RFC Guide)

🗝️ Key Things to Know

Webhooks are real-time and push-based—no polling needed.
Postmark does not store webhook events if delivery fails repeatedly.
Debugging often requires checking logs on your own server.
For added security, you can use Basic Auth or IP filtering.