Webhook vs. Api — What's the Difference?

A while ago I wrote an article here at Snipcart about the difference between APIs and microservices. I started off that article by complaining about how in the good old days, I didn't need to know any of these fancy-schmancy terms to make myself a good website. But by the end of that article, I changed my tune: these "big words" were actually highly useful concepts that let me make my wildest ideas into reality.

Well, I'm back.

This time writing an article comparing webhook vs API.

They're similar techniques, so they get confused every now and again. We often see these terms sprinkled throughout tool documentation and technical articles, and often, they're just stuck in without any explanation.

Today, let's dive a little deeper into these concepts to figure out what the difference is and how we can use both in our applications to actually implement those wild ideas.

Webhooks & APIs technical definitions

Here's my API definition from the last article:

API stands for Application Programming Interface. According to Wikipedia, an API "defines interactions between multiple software applications. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc." In the web development world, we often use APIs that can be accessed through the Internet.

OK, so that might be a little hard to follow. Bear with me here, we're going to translate it into simple English in a second.

Here's the technical definition for webhooks too:

A webhook is an event-based API endpoint responsible for triggering internal functions instead of existing ones to look up information. According to Wikipedia, "a webhook in web development is a method of augmenting or altering the behavior of a web page or web application with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application... The format is usually JSON. The request is done as an HTTP POST request."

What does this mean IRL

OK, let's translate that into simple English:

API stands for Application Programming Interface. APIs define how two pieces of software can connect and talk to each other. On the web, that means that other programs (like your client-side JavaScript) can use it to look up the information on your server that it has permission to access. Think of it like this: if your server-side application was a big company, your API would be the team whose job it is to respond to inquiries from external parties (customers or company partners, for example).

Webhook

A webhook is an API endpoint that serves a different purpose: instead of just being there to look up information like a typical GET API endpoint, we can POST to the webhook with some JSON data, and then it'll do something internally. That means webhooks can serve as a sort of event system. Using the same company analogy, if the API is like the team responding to inquiries from other parties, webhooks would be the team that takes action when an approved partner says it's time, like the team who updates the inventory when the supplier says they have more items in stock.

So basically, webhooks are like anti-API endpoints. They take in data and do internal work where regular API endpoints return data so that the client asking for that data can do something with it.

OK! So that probably answers your question, right? You found your way to this article trying to work out the difference between APIs and webhooks, and there it is, explained in two easy sentences. So are we done?

Didn't think so. You want to see this in practice... well alright then! Let's jump in.

An example of an API out in the wild

Last time we talked more about how to use APIs, especially in comparison with microservices, but for a quick recap:

APIs are there to regulate how information is passed between a client and server. It sits as a middleman between them.

So in that sense, we use APIs for pretty much everything! Building a web app without APIs is almost impossible.

For example, if you open up a new tab and Google the weather in your hometown, you'll see a neat little widget. Google doesn't actually own that information. They aren't out there collecting weather info from around the world, and especially not so in this tiny town in rural Pennsylvania. But somehow, they've filled out this little widget:

So, where did all that weather data come from if Google didn't collect it themselves? Well, if you take a look at the bottom right, you'll see that they sourced it from weather.com (which is owned by IBM). How did the data get from weather.com to Google?

Via an API!

When I searched for weather in Shrewsbury, PA, Google quickly sent a message to IBM's servers saying Can you return the data for the weather in Shrewsbury, Pennsylvania please? and IBM responded Sure, it's 71 degrees Fahrenheit right now. Obviously, they did this in code, but it's helpful to think about it as a conversation.

That's completely expected, right? Google should be able to ask IBM for weather data like this. But in this model we've imagined here, Google could've asked anything! Imagine if Google said, Hey IBM, update the outside temperature in Shrewsbury, PA to 1000 degrees in your database. That wouldn't be good!

APIs solve this problem by whittling down what the client (in our example Google) is allowed to ask the server (in our example IBM's weather servers). Take a look at this demo to see what I mean. If you open the dropdown menu under Default, you'll see this:

What IBM has done here is allow clients of this API (in our example Google, but this also applies to you if you want to use it) to ask two questions. You can ask a question by sending an HTTP GET request to the appropriate endpoint (that long bold monospaced thing with the slashes). Your possible questions are:

1. Hey IBM, can I please have the weather data at x latitude and y longitude on z day?

2. Hey IBM, can I please have the weather data at x postal code on y day?

That's it! Just two questions. Now Google can't do anything nefarious...

Webhooks in the wild

OK, so where can we find webhooks in the wild?

Remember how I said earlier that it'd be a bad idea for Google to be able to tell IBM to update their database?

Well, I kinda lied... Sending data back to IBM so they can do something with it could be a useful thing to be able to do!

For example, let's take a look again at that weather widget:

Previously, I directed your attention to the bottom right near the weather.com link. Perhaps you noticed the inconspicuous button at the bottom that says Feedback? Let's click it.

OK, interesting. So, some of these are obviously feedback for Google's use, like "This isn't useful", or "The page took too long to read". But one of them is more likely to help IBM out: "The weather is wrong". This is where things get really fun.

So IBM obviously shouldn't just let anybody give them feedback, or else they'd be so swamped with terrible feedback that they wouldn't be able to find the good stuff. On the other hand, Google is used to sorting through feedback. That's a big part of their business. So assuming Google has compiled all of the good feedback and weeded (wed?) out all the useless stuff, then they're going to have a big packet of useful feedback that IBM is going to want.

Let's dive a bit into how they might set that system up:

1. First, IBM is going to need to set up an API endpoint that Google can POST to send over their feedback.

2. As I mentioned, IBM won't want feedback from just anybody, so step 2 is going to be authentication. They need to verify that the originator of the request is Google using some auth system.

3. Then using that data, IBM can store it in their database and update their weather data accordingly.

That API endpoint seems like it works a bit backward, right? Instead of getting information like a typical request, it's sending information to IBM — it does the opposite of your everyday API endpoint! This technique has a special name... we call it a webhook. 😉

There are so many cool things we can do with this! A lot of more complicated processes are just too complex for a single API request, so it gets split out into a few successive requests and webhooks. That's how, for example, Stripe Connect works. Your user can go through a whole process on Stripe's site, which lets Stripe handle all those complexities, and then when they're done, send a POST request to one of our webhook endpoints with the user's new Stripe Connect ID. Then we can store that in our database and use it to interact with Stripe on the user's behalf.

TL;DR

Are webhooks API requests?

Well, sort of, it is kinda a gray area. They are API requests, but they help the server instead of the client, so they do the opposite of what we normally think of as API requests. Clients make requests to an API to get data from the server as opposed to webhooks that push data to a server from the client.

Here are a couple of resources you might find useful if you want to learn more:

Now I'm quite proud of that nutshelling, but if you've got any more questions, feel free to reach out! I'm @jadenguitarman on Twitter — please DM or @ me for help.