CodeAnalogies Blog

If you have ever gone pumpkin-picking or apple-picking during the fall, then you can understand webhooks.

Webhooks are an exciting alternative to APIs that have grown in popularity over the last 5 years.

In fact, if you have ever used a service like Zapier or IFTTT, then you have probably already used a webhook yourself!

Regardless, if you are a web developer, you are going to need to understand how webhooks actually work before you can use them in your own web apps.

I wanted to create an easy way to explain how webhooks work by comparing and contrasting them to application programming interfaces (APIs).

In order to understand this tutorial, you are going to need to understand APIs first. Here is my guide to APIs, which I will briefly summarize before getting into webhooks.

Web APIs Explained by Selling Goods From Your Farm

APIs are request-based, meaning that they operate when requests come from 3rd party apps. Webhooks are event-based, meaning that they will run when a specific event occurs in the source app.

In this tutorial, you are going to be running a farm that has some year-round products, like eggs, and some seasonal products like pumpkins. Yes, it is your job to satisfy the annual pumpkin craze that happens every fall.

Pumpkin pie.

Pumpkinseed salads.

Freakin’ pumpkin flavored muffins!

How do APIs work?

Here’s a quick summary of the way that APIs work. As a farmer, you need to sell products to distributors and restaurants in order to stay in business. Your customers will then stock your eggs, corn, pork and whatever else in their grocery stores or include it in their meals.

So, if a person eats an omelette at a local restaurant, they may be “using” your product… even if they do not know where the eggs came from!

But, since you are running the farm, you also need to make sure that you have enough supply to feed all the demand before you start selling a product to restaurants/distributors. You don’t want to stress out all your staff and chickens while trying to produce enough eggs on a weekly basis! This is the concept of an API endpoint– you only want to open up the endpoint if you know that you have the capacity to handle the requests.

Every time a truck from a customer visits your farm to pick up your products. there is an API call. The truck is “requesting” data via a GET or POST request from your servers.

Here is the technical version of that diagram.

So then what is a Webhook?

Every year in the United States, the annual pumpkin-flavored craze happens. For about 10 weeks during September, October and November, retailers and restaurants release special versions of their food (or new items) that include pumpkin flavors. And then their customers go crazy!

Let’s assume that restaurants will only buy from their local farms, like yours. Imagine if these restaurants handled the season in a request-based manner. That means they would send a truck every single day of the Fall and eagerly ask,

“Are the pumpkins ready yet?”

As the farmer, you would wake up every day to a line of trucks anxiously awaiting your report. This is annoying for everyone involved.

Request from restaurants: Are the pumpkins ready yet?

Response from farmer to each restaurant: No!

This is called polling the database. It happens when 3rd party developers are checking for an update to the data on your servers.

Based on a number of factors, like weather, temperature, and pests, your pumpkins will be ready at a different time each year. It would make more sense to make this event-based. The restaurants could all give you their phone numbers, and as soon as your pumpkins are ready, you can give them a call for them to come pick up their order. The restaurants must specify in advance exactly what they want.

This is similar to the way that webhooks are actually applied.

First, the webhook provider (farmer) creates a webhook that will alert third-party apps when a specific event happens.

The third party app developers must provider a listener (phone number), or a URL, in advance that will handle the request.

Finally, when the event actually happens, the webhook provider sends a POST HTTP request to the provided URL. After that, the third party app developer can use the data on their own servers.

That is why webhooks are sometimes called “HTTP callbacks”– because the HTTP request is triggered as a callback after a specific event happens on the webhook provider’s servers.

Let’s walk back through all of this one more time with the pumpkin example.

1. The pumpkins are ready to be sold for the fall season (event)
2. Farmer calls the restaurants (webhook provider collects data, ready to share along listener)
3. Restaurants come get their beloved pumpkins (POST request fires as callback)
4. Restaurant does what it wants with data (action within 3rd party app)

This could technically be solved with an API as well, but it does not make a ton of sense to do it that way since the developers on your API would need to continually poll your servers, looking for new data.

Example of Setting Up Webhooks

Let’s walk through the steps you might actually use to set up a webhook in an app. I will use MailChimp as an example, since that is a very popular email marketing tool.

If you are not already familiar, MailChimp allows entrepreneurs and marketers to build email marketing lists and send emails either manually or in automated sequences.

Their webhook documentation shows that there are a couple events that you can use to trigger a webhook:

• Someone joins the marketing list
• Someone unsubscribes
• A list member changes their email
• …and more!

Let’s imagine that you only want to know when a new member subscribes to your list.

To get alerts about these events, you must first input the callback URL.

So, if your domain was pumpkinfarmer.com, and the URL for the POST request was /emailEvent, you would input:

https://pumpkinfarmer.com/emailEvent

They allow you to choose which events you would like to be informed about:

In this case, you would only check the box for “subscribes”.

Once you set this up, you will get POST requests at the specified URL. According to their Webhook examples page, their request looks like this:

This is all the data surrounding one new subscriber to your list. After that, you can trigger some action in real-time, like updating your database of all subscribers.

Here is the final diagram of that process:

Get The Latest Tutorials

Did you enjoy this tutorial? Check out other explanations of web development topics at the CodeAnalogies blog, or sign up for the latest tutorials here: