MailerSend
Blog

Subscribe to real-time notifications using webhooks

Agathe Brusset Agathe Brusset
· 5 min read · New features and updates · February 5th, 2021
Here’s a quick overview on how to use webhooks to monitor email events as they happen and get notifications in real time.

Are you constantly polling the API to get up-to-the-minute updates on your transactional email events?

Let’s face it. Polling is a waste of your time and your server resources. Plus, there’s a risk that you may miss out on an event in between your requests because you’re sending requests in a pre-determined order—not in response to an event.

There’s now a smarter way to receive updates. We’ll show you how MailerSend’s webhook feature will let you subscribe to notifications about various email events without having to poll the API.

What are webhooks?

Typically, when you want to check for new data with an API, you’ll send a request and then wait for a response. And you’d repeatedly “pull” data to stay up to date. Such constant polling of the API server, however, is time consuming and resource intensive.

A webhook—also known as an HTTP callback—makes HTTP POST requests to a URL endpoint. Once set up, event notifications are “pushed” to your URL in real time. With webhooks, you don’t need to constantly send requests but rather you can simply wait for a response.

Once you’ve tried webhooks, you’ll see how they can be used in many ways in your stack to receive email notifications.

How to set up webhooks

Set up webhooks with the app

It’s easy to get started with webhooks in MailerSend. Go to the Domains page, find the Webhooks section, and click on “Add webhook”.

Add a webhook dialogue box

Here, give your new webhook a name and point it to the endpoint URL that you wish to receive the HTTP callback. You may be able to find this URL in the app that you want to send the notifications to.

Next, select the email events that you would like to monitor. Or click on “Receive all events” if you wish to monitor them all. You can choose from the following options: 

  • Sent

  • Delivered

  • Soft bounced

  • Hard bounced

  • Opened

  • Clicked

  • Unsubscribed

  • Spam complaint

Click on “Save webhook”. You’ve just created your first webhook!

Set up webhooks with the API

Alternatively, you can also create a webhook using our API. We’ve got a detailed API reference that shows you how.

Using and managing webhooks

Once your webhook is saved, you’ll find it listed under the Webhooks section. You can manage your webhooks by clicking on “Manage” or the webhook name. Webhooks can also be paused or deleted here.

Add new webhook dialogue box dashboard - mailersend

Going further into your webhook’s details, the secret webhook key to be shared with the receiving app is displayed here. You can also verify your webhook’s signature.

Webhook signing secret dialogue box

All webhook attempts made in the past 7 days are also shown here for troubleshooting purposes: all 2xx answers are shown as successes, others as failures.

On every failure, MailerSend makes a retry 10s after the 1st attempt, and then 100s after the 2nd attempt. This avoids hammering the application you want to send the information to.

On this page, you can edit your webhook’s details at any time. Click on the “Edit” button to change your webhook’s name, URL, status, or the email events that you’re monitoring.

Webhook details dialogue box - mailersend


What you can do with webhooks: 3 use cases

You made it through the setup sections in one piece! Now it's time for your reward—use case examples that showcase the usefulness of webhooks.

1. Remove hard bounced emails from your list

If your email marketing platform supports webhooks, you can automatically remove hard bounced emails from your email list. Take pre-emptive steps to protect your sender score and email deliverability.

Create a webhook that listens for emails returning a hard bounce: activity.hard_bounced. When triggered, your app can mark the subscriber as “unsubscribed”, automatically keeping your mailing list clean.

2. Know when recipients have read your emails

You’re setting up a helpdesk project and you want to implement a “seen” feature to know when customers have read your emails.

Simply create an endpoint to monitor for activity.opened events and send the webhook’s payload to your helpdesk app.

3. Understand the behavior of your recipients

Your marketing team wants to understand how recipients engage with your MailerSend messages. They want to be notified in Slack whenever recipients bounce, opt-out or complain about your transactional emails.

Firstly, create a Slack app and enable the Incoming Webhooks feature. Pick a channel that you want to send notifications to and a webhook URL will be generated for you. This is the endpoint URL that will receive all HTTP POST requests.

Next, create a webhook in MailerSend and paste the Slack webhook URL. All events like activity.hard_bounced, activity.unsubscribed and activity.spam_complaint will now be sent to your Slack channel for further action.

More webhook resources

Check out our website for more help resources:

Work smarter with notifications

Webhooks enable you to easily connect MailerSend with the rest of your stack. And they’re a more efficient way of getting instant, real-time notifications about email events. Plus, they’re much easier to set up and maintain than making requests to an API. We hope this article has inspired you to automate your product and workflows by listening to and acting on events with webhooks.

We’d love to hear what use cases you’ve been facing in your business with webhooks. Share in the comments!

Agathe Brusset
I'm Agathe, Product Manager at MailerSend. When I'm not busy rolling out new product features, I'm planning my future mud-brick farmhouse complete with farm animals and a vineyard!