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. Under the“Settings” tab, select“Webhooks” and then click“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. The open webhook, you will see the option for "Post only on first open" checkbox. Post only on first click will only notify your server when a user clicks a link in your message for the first time. 
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.  
TheRecordType” 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!

Note: When setting webhooks with our API, you can only set 1 webhook URL per event. Currently, it's not possible to set up modular webhooks with the public API. We have plans to update this in the future, but for now, modular webhooks can only be set up in the UI.

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 March 26th, 2018

Still need some help?

Our customer success team has your back!