APIs have become the bedrock of connecting customers and partners in a digital world.
But they get confused now and then with a similar technique called webhook. As a result, we often see these terms sprinkled throughout tools documentation and technical articles, and often, they're just stuck in without any explanation.
Here’s a quick explanation of how webhook compare to API:
An application programming interface (API) is a software interface that serves as a bridge between computers and applications. A webhook is a way for one application to deliver data to another app in real-time. Both enable different systems to share information and sync up, but they do it differently and for different purposes.
Let’s dive a little deeper into APIs and webhooks to figure out the difference and how we can use both to implement them in our applications.
What is an API?
API stands for Application Programming Interface. It defines the interactions between multiple software applications. It allows you to set the kinds of polls or requests that can be made, how to make them, the format of the data used, etc.
In the web development world, we often use APIs accessed through the Internet to communicate to external applications.
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.
What is a webhook?
A webhook is an event-based API endpoint responsible for triggering internal functions to look up information in real-time when a specific event occurs. In web development, it's used to augment or change how a web page or web application behaves via 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 terms:
Think of it like this: if your server-side application were a big company, your API would be the team whose job is to respond to inquiries from external parties (customers or company partners, for example).
A webhook (sometimes called a reverse API) is an API endpoint that serves a different purpose: instead of just looking 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.
Let’s use the same company analogy we used earlier. If the API is like the team responding to inquiries from other parties, webhooks would be the team taking action when an approved partner says it's time. Just 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 standard 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.
Where APIs are used?
Last time we talked more about how to use APIs, especially in comparison with microservices, but for a quick recap:
APIs 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.
Here's a use case:
If you open up a new tab and Google the weather in your hometown, you'll see a neat little widget. Google doesn't own that information. They aren't 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 new 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 updates 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:
IBM has done this here to 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:
Hey IBM, can I please have the weather data at x latitude and y longitude on z day?
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.
APIs are beneficial in this case since there's a constant change in data.
Where webhooks are used?
OK, so where can we use 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 lied. Sending data back to IBM to do something with it could be a helpful thing to do.
For example, let's retake a look 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.
This is where things get fun. Some of these are feedback for Google's use, like "This isn't useful" or "The page took too long to read". But one is more likely to help IBM out: "The weather is wrong".
Obviously, IBM 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 excellent feedback and weeded (wed?) out all the useless stuff, they're going to have a big packet of helpful feedback that IBM wants.
Let's dive a bit into how they might set that system up:
First, IBM will need to set up a REST API endpoint that Google can POST to send their feedback.
As I mentioned, IBM won't want feedback from just anybody, so step 2 will be authentication. They need to verify that the request’s originator is Google using some authentification system.
Then using that data, IBM can store it in their database and update their weather data accordingly.
That API endpoint seems backward, right? It's sending real-time data to IBM instead of your typical endpoint. This technique has a particular name; we call it a webhook.
There are so many cool things we can do with this! Many 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.
Are webhooks API requests?
Well, sort of, it’s a gray area. Clients make requests to an API to get data from the server instead of webhooks that push data to a server from the client. They are API requests, but they help the server instead of the client, so they do the opposite of what we usually think of as API requests.
Here are a couple of resources you might find helpful if you want to learn more:
What are webhooks? - Zapier
Now I'm pretty 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.