One of our most popular features in Postmark is webhooks, which give you the ability to receive real-time notifications for events like bounces, opens, and clicks in the form of HTTP POSTs to a URL you specify. This allows you to take action on various email events without having to make any calls to our API. For example, you can use bounce webhooks to mark an email address in your application as inactive, and provide your users with a way to correct their email address if they entered it incorrectly in your application.
Up to now these webhooks have been limited. You were only able to add a single URL for an event, and you were only able to get notifications for one event at a time. It’s still a useful feature, but this 1:1 relationship between URL and event was holding back some of the more powerful things you can do with webhooks.
Well, we’re happy to say that with the introduction of fully modular webhooks, all of that is changing today. I’ll first list out all the new functionality we released today, and then go into more detail on the UI changes. Here’s what’s new:
- With modular webhooks you can now choose which events you’d like to send to each specified URL. Want to send Open and Click events to the same URL? You got it. Want to drink from the firehose and send all events to a single URL? Have at it!
- With this change, you’re also now able to add up to 10 URLs for us to POST to. Let’s say, for example, you want to get Bounce events to your internal system, but you also want to use our nifty Slack App to send Bounce notifications to a channel of your choice. You can now do that!
- In the past, the Spam Complaint event was part of the Bounce event. This created a bunch of confusion and frustration, since spam complaints generally require different actions than, say, a hard bounce. With this release Spam Complaints have been moved out into a separate event, so that problem is also a thing of the past.
- You’ve always been able to add basic HTTP auth via the webhook URL, but we’ve now added HTTP auth fields in the UI as well.
- We added an option to include up to ten custom HTTP headers with every webhook.
- Webhooks now live in their own tab on the Settings page, instead of being buried in the “Outbound” tab like it used to be. Note that the Inbound webhook remains in the “Inbound” tab for now.
Adding and managing modular webhooks #
The main webhooks page now looks like this, and will list out all the webhooks you’ve set up:
To add a new webhook, click the “Add webhook” button, which takes you to a basic two-step process:
- Enter the URL where you’d like to receive HTTP POST requests.
- Select which events you’d like to get notifications for. Choose from Delivery, Bounces, Spam complaints, Open, and Link clicks.
You can then test your webhook by sending some sample JSON to the URL before you save it. If you’d like to add custom headers and basic HTTP auth, you can do so by expanding that section, but this is optional:
You’ll notice that we added a
RecordType field to the JSON payload to identify the different events you’ll receive in each webhook. Have a look at the developer docs
One important note: we did not update the Servers API with this release. This won’t affect many of you, since that API is only used to set up or edit new webhooks — most customers do this via the UI. But for those of you who use the API to manage webhooks, the existing API endpoint will continue functioning as it does currently. You’ll be able to set one webhook URL per event, and change that URL. But you won’t be able to set up modular webhooks with the public API yet — you’ll have to use the UI for that. We’ll release a future update to bring this functionality to the Servers API as well.
What about the “old” webhooks? #
We haven’t changed the payload format for existing webhooks, so everything you’ve set up will continue working as before. For example, if you have currently have a bounce webhook defined, it will still post both bounces and spam complaints to it as it did before. If you’d like to split out spam complaints, you’d have to change your existing webhooks to be modular.
And that’s it! We’re excited to see how you use this new webhook functionality. So, in addition to our usual request to let us know what you think and how we can improve, we’d love it if you could tell us how you’ll be using this feature. Drop us a line at email@example.com.