How do modular webhooks work?

With Postmark’s modular webhooks you can receive real-time notifications for events like bounces, opens, and clicks in the form of HTTP POSTs to a URL you specify. Webhooks are grouped by six supported event types:
  • Delivery
  • Bounces
  • Spam complaints (a spam complaint is recorded when a user clicks This is Spam or Mark as Spam in email clients like Yahoo, Hotmail, AOL, etc.)
  • Open
  • Click
With modular webhooks you can do the following:
  • Add up to 10 webhooks with any combination of events.
  • Choose which events you’d like to include in each URL.
This help article will show you how to add and test your webhook URL.

Add your webhook

Log into Postmark and open the Server you want to configure the webhooks for:
  1. Choose the Stream
  2. Select Webhooks
  3. Then choose Add webhook
In the Webhook URL field, enter in your URL where you want to receive the events. When adding or editing a webhook, you must specify the event type and a valid URL.

Select your events

For the Bounce and Spam Complaint webhook, you’ll see the"Include message content" options. Message content includes the content type and body of the message. For the Open webhook, you will see the option for "Only post on first open". With this checked, Postmark will only send a webhook on the first time a message is opened.
You can add up to 10 webhooks with any combination of events.
Note: You can also attach up to 30 custom headers and basic HTTP auth credentials. If you leave these values empty we will use our default headers which are:

Content-type: application/json

User-agent: Postmark

Test your webhook

Before saving the URL, be sure to use the “ Send test” button to send a test event to your webhooks URL. If you’ve selected multiple events for one webhook, you can select the event you want to test in the dropdown option next to the“Send test” button.
The RecordType” field is used to determine which event you’re receiving data for.
Please note: Hooks need to respond with a 2xx in order to be successful.

Save your webhook

Once the test is successful, click “ Save webhook” at the bottom of the page. ( see image above)

Now you’re webhook is set!

Testing webhooks with Postman

Postman is a free API client that you can use to manage and execute your APIs. With Postman, developers can create, share, test and document APIs by allowing users to create and save simple and complex HTTP/s requests, as well as read their responses. It’s also great for sending mock request to your webhook URLs. After you’ve installed Postman, you can download our webhook collection here to get started.

What about the old webhooks?

If you're using our old webhooks, there's no need to change anything. Webhooks will send new JSON fields, but existing fields will remain the same.
Last updated February 14th, 2020

Still need some help?

Our customer success team has your back!