📬Webinar: Introducing Broadcast Message Streams Learn all about Postmark's new Broadcast Message Streams and the types of bulk messages that are a good fit for sending!
x

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:

* The Bounces webhook and the Spam Complaints webhook are not available for Broadcast Message Streams.

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
    Add webhook button
  4. 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.
    Webhook URL field

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

Edit webhook screen

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 your 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 June 10th, 2020

Still need some help?

Our customer success team has your back!