What Is a Webhook and Why Do You Need It?

Wondering what is a webhook and how it works?

Well, just think about the amount of information you get about the emails you send. We’re sure you love all the detailed stats Mailjet offers, but you wish there was just a way the right ones would come to you, so you wouldn’t need to you looking out for them. Well, luckily, there actually is. Today, we’ll tell you all about webhooks, how to set them up and how to use them to drive your email program.

What is a webhook?

Imagine that you have an online store and you want to offer a special discount for anyone opening your email in the first 24 hours. You can do it manually, by checking your email stats regularly and manually sending those who opened the discount code. But that would take you a lot of time, right?

Or you can do it automatically with webhooks, which will trigger a message with the additional discount to anyone that opens your email. Sounds more efficient, right?

Simply said, webhooks are events that trigger an action. In most cases, they are used for communication between systems. This is the simplest way of getting an alert when something happens in another system. They are called webhooks because they work as software hooks over the web.

How do webhooks work?

Let’s take your bank as an example. When you make a withdrawal using an ATM, the machine checks your balance and gives you the amount you requested. Once this operation is done, your balance is updated and this change triggers an action – an SMS is sent with the details of the withdrawal.

That’s how webhooks work. An action serves as a trigger for another action. The rest is a popular architecture used to communicate between systems.

A webhook is a HTTP callback: a HTTP POST that occurs when something happen – an event-notification via HTTP POST. Webhooks are used for real time notifications, so your system can be updated right when the event takes place.

Most commonly, webhooks are HTTP callback points that are defined by the user. They allow you to register an http:// or https:// URL where the event data can be stored in JSON or XMLformats. After that, you will be able to do what you want with the data you retrieve and store from a certain event.

The core mechanics of webhooks consist on making an HTTP request to a user’s specified URL. A webhook makes an HTTP callback to a URL that has to be configured by the system which receives the data.

That URL is called webhook endpoint. Webhook endpoints need to be public and it’s important that this URL belongs to the receiving system. The callback is triggered whenever there is an event you’d like to notify another system about.

For Mailjet, this webhook is a URL you can add in our system, so you can receive email events, such as “sent” “open, “clicked”, “bounce”, “block”, “spam” or “unsubscribe”. This way, you can either track your messages the whole path, of your message or just “listen” for the status you want.

Let’s go back to the ATM example. When you make the withdrawal, your bank is notified and updates your balance, which is the indication for the system to send you an SMS with all the details.

Webhooks work on the same concept. The ATM is a third-party app/site (webhook provider) that sends a signal when a specified event occurs. The system that sends you the SMS is what is known as the “listener”. The listener is the URL that receives the webhooks calls and performs a predefined action after that – in this case, sending the SMS. Webhooks are a programming mechanism designed to receive data that originates in some external system, in real time. In this case, that system is the bank account. Is it clearer now?

But what sort of things can you do with webhooks? Among other things, you can:

• Synchronize systems in real time;
• Send any kind of notification;
• Process the data however you want;
• Create reports;
• And almost anything else you can think about!

Why do we need webhooks?

There are two ways your apps can communicate with each other to share information: polling and webhooks. In our example with the bank, polling would be going to your bank and asking what your balance is each time you make a withdrawal.

Nowadays, everyone needs a simpler way to get data out in real time, so they can easily do whatever they want with it. That means, no polling every minute for large exports that your system would then need to parse, risking a system overload or losing the data if there’s a bug. Using HTTP is a simpler and easier solution, as webhooks are automated messages sent from apps when something happens.

Source: Cloud Elements – check out their post to learn more about the difference between polling and using webhooks.

There are two ways you can use webhooks:

1. To receive the event information and store it;
2. To receive the event information and pass it on;

Let’s look into these two scenarios closer.

To receive the event information and store it:

The so called “push” is the simplest way to use webhooks. As we already mentioned, there is no need to be polling your data every few minutes to find out if there is new information. You can just get the new information directly by using webhooks. You will be able to store it till you need it for something else. Basically, the system you configured with your webhook will PUSH the information you need when it arrives.

To receive the event information and pass it on:

The so called “pipe” happens when your webhook not only receives the information for which it listens, but goes on to do something new with it, like triggering actions. You could create a script, register its URL on your site, and send an email when a visitor creates an account. Or create a script that updates the quantity of products available every time a new purchase is made.

With webhooks, you can actually do whatever you want or need! And it is simple and efficient, because you are not wasting your time requesting for enormous amount of data – you are receiving the new data when it arrives!

How can you use webhooks with Mailjet?

With webhooks, you can easily receive each open or click event right after it happens, or track bounces and blocks as they happen. Imagine that in 15 minutes more than 60% of your emails to a destination are blocked? Thanks to the events you are receiving in real time, you’ll be able to detect this immediately and take action.

You can always use the events to create your personalized dashboard in whatever internal application you use, to process the data you want as you wish. You’ll only have the events you need and track the most relevant data. Or you can use the events received on your webhook as triggers for a new email to be send, to create a personalized automated flow for all of your users.

Mailjet event examples

Let’s dig a bit deeper into what the events you receive on those webhooks look like.This is what you’ll get when you receive an open event:

{
“event”: “open”,
“time”: 1433103519,
“MessageID”: 19421777396190490,
“email”: “api@mailjet.com”,
“mj_campaign_id”: 7173,
“mj_contact_id”: 320,
“customcampaign”: “”,
“CustomID”: “helloworld”,
“Payload”: “”,
“ip”: “127.0.0.1”,
“geo”: “US”,
“agent”: “Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0”
}

You can see what message was opened, when exactly and other useful information that you can use however you wish.

Now, let’s check out a bounce event:

{
“event”: “bounce”,
“time”: 1430812195,
“MessageID”: 13792286917004336,
“email”: “bounce@mailjet.com”,
“mj_campaign_id”: 0,
“mj_contact_id”: 0,
“customcampaign”: “”,
“CustomID”: “helloworld”,
“Payload”: “”,
“blocked”: true,
“hard_bounce”: true,
“error_related_to”: “recipient”,
“error”: “user unknown”
}

Here you can also see what the error was, in the field “error”. In this case, the error indicates it’s an “unknown user”, which lets you know that it is better not to try and reach out to this user again. This could be used to synchronize two systems to clean your lists from inactives or incorrect contacts.

In shortly, you can do anything with the events you receive from Mailjet. Use them in your configuration and create what you need!
How can you configure a webhook with Mailjet?

First off, you’ll need the URL from the system from which you want to receive the events. Once you’ve got that, everything else is really simple. That URL will accept data and can activate a workflow to turn the data into something useful. There are two ways to configure your webhooks in Mailjet.

• Using our API;
• Using our interface;

Using our API

You will need to make one simple call to setup the URL you want to use. Here’s the call:

curl -s \
-X POST \
–user “$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE” \
https://api.mailjet.com/v3/REST/eventcallbackurl \
-H ‘Content-Type: application/json’ \
-d ‘{
“EventType”:”open”,
“Url”:”https://mydomain.com/event_handler”,
“Version”:2
}’

This URL will listen for open events. Each time anyone opens your email you will receive an open event like the one we saw above. Then you can either just store the data or trigger an action, such as sending a new email.

See, it is simple! One call and everything is done. Check out our documentation to get started.

Using our interface

We offer the option to configure the webhook from our interface as well. You can do it from the “My account” page, on the section “Rest API”. You’ll need to choose the option “Event tracking (triggers)”

You’ll be able to add one webhook for all events, or set up specific ones for each type of events.

You will be able also to test the URL you specified to ensure it’s working properly. If all goes well, it will return a 200 OK HTTP. Any other HTTP code will result in our server retrying the request later.

Our system will retry following these rules:

• 10 attempts, with 30 seconds between each attempt;
• After that:10 attempts, with 30 minutes between each attempt;
• If none of these attempts work, the URL will be suspended;

Keep an eye on your webhook for any responses other than a 200 OK.

And this is it! You have a functional webhook that can receive your email events. Use this in your configuration to have your own statistics or custom workflows.

Summing up

Now you know what a webhook is and why this is the easiest way to track any type of events over the web. Just set up your “listener” and decide what to do with the events it catches.

Using Mailjet’s events will help you track everything that happens with your emails. This is the perfect way to clean your lists or to create your own dashboard in your company’s internal application.

If you want to be the first to know about the latest tech trends or how to use Mailjet, follow us on Twitter and Facebook.