API vs Webhooks: How to Know When to Use Each

API vs Webhooks

Applications on the internet today rely a lot on third-party integrations. And why shouldn't they, when it helps developers focus more on the core product than tangling with different features? For instance, you could use a simple tool to handle your email marketing campaigns, or you could use a third-party payment provider to handle all the payments on your website.

However, as third-party integrations diversify, developers have found a way to transport lightweight data that makes the lives of marketing and products folks easier. It's all thanks to this new buzzword called webhooks.

Well, "webhooks" is much more than just a buzzword today! A webhook is a new way to share data that's easy to implement. However, its similarity with APIs often leaves room for confusion among developers.

To demystify that confusion, this post will talk about what webhooks are and how they're different than traditional APIs. We'll also look at some of the practical use cases of webhooks in great detail.

A Refresher on APIs

Before we define what webhooks are, it's important to know what they aren't. Since we're comparing them to APIs, it's best we understand what exactly an API is.

An API (application programming interface) is a web service that allows your application to interact with a database. Now, your application could be anything: an e-commerce site, a SaaS product, or a networking app. When you want to display some dynamic data in it, you'll call an API. Or when you want to update some entries of a particular user, you'll call an API.

Structure of an API

An API typically consists of two components—a request and a response. The request is what triggers the API or the input it receives. The response is what the API gives away as an output. The client or the caller receives back this response from the API.

Amid this structure, an API could be of any type—GET, PUT, POST, DELETE, etc. These are request types that tell an API what kind of action it has to perform.

To understand further, let's take a look at a simple use case where you need an API.

Example of an API

Let's say you have a networking app for freelancers. You visit the profile page of a freelancer, and you wish to know more details about them. As a developer, you'd think, Well, no biggie I'll just add a button there to view more details. That's all cool, but when a user clicks that button, what you need to do is grab that additional data and show it to the user.

The workings of an API

So now your application requests that data via an API request. The API fetches the relevant data from the corresponding database. Then, this data is wrapped into JSON format and sent back to your application.

So that's an API in a nutshell. Maybe you knew that already, but it'll help you understand better what webhooks are and how they're different.

What's a Webhook?

Webhooks are a type of web service that sends some lightweight data when an event is triggered. They're used as a tool that notifies your application when certain user-driven events or actions are complete.

Remember I mentioned how third-party integrations are driving tech products today? Webhooks become interestingly important when you integrate third-party applications or services into your software. This is because when these applications finish an action for your software, you need an automatic update on the status of that action. That's exactly where webhooks come into play.

Let's look at an example to understand the workings of a webhook by examining a use case.

Example of a Webhook

Let's say you're the developer of a SaaS platform that millions of users have subscribed to. Since you want users to use your product, you have a free tier as well.

Now imagine there's a new user who's currently on a free tier but wants to upgrade to a premium subscription. Naturally, the user goes to your app and proceeds to make the payment. The payment provider asks for the user's details and tries to process the payment.

There are multiple scenarios possible now. The payment could fail instantaneously if the bank's server is down. Or the payment could take some time to complete due to the heavy load on the server. However, most likely, the payment could successfully go through. When that happens, a payment completion event occurs, which triggers a webhook.

This webhook now updates the user's tier from free to premium.

The workings of a webhook

But I know what you're probably thinking. Why not just get that updated status of the payment via an API call?

Think about the multiple scenarios I mentioned above. You don't know when the payment would be completed. You'd need to continuously make an API call till you receive a response. You'd need a custom retry mechanism with timeouts. Definitely an overkill!

Instead of asking for the status of the payment every now and then, you can tell the payment provider to inform you when the payment is completed.

How Webhooks Differ From APIs

We have laid down the definition of each type of web service. We know what webhooks are and what APIs are, and we have also seen a practical example of each.

So let's extend that knowledge to understand how they're different from one another.

Mechanism

APIs are driven by requests. Your client or software will have to make an explicit API request to get some response back from the API. This also means you're explicitly writing a curl request or a fetch request to make that API call. If the request involves having to pass some parameters, you'd have to send those as well.

Webhooks, on the other hand, are driven by events. These events are mostly tied to the journey of your user. So when a user performs an action on your application or software, a webhook may be triggered. In most scenarios, you won't be writing extra code to trigger a webhook.

Structure and Complexity

There's a GET API to fetch some data, a POST API to write some data, a DELETE API to delete some data, and so on and so forth. APIs have a fairly complex structure when it comes to using them. There's a different API request for different types of use cases. They may also send some complex and nested JSON data back. All in all, they require more server resources than webhooks. In a way, an API becomes a full-blown web service that carries out resource-intensive tasks.

Webhooks have a simple structure. They only send some data to the caller. Since the web service becomes minimal in this respect, it's not as resource intensive as an API. Since the data they send is simple, it's much more lightweight in this aspect.

Communication

APIs provide two-way communication between the caller and the API itself. In other words, the client is making an API call to interact with the API. The API sends back some response to the client and interacts back with the client or the caller.

Webhooks follow a unidirectional communication with the caller. The main application only receives some data. It doesn't directly interact with a webhook. Instead, it interacts with the caller that further triggers the webhook. In a way, your software or application only receives some data from the webhook.

Isolation

A user interacting with your application may see all the API calls from the network tab if your application sits on a web browser. Moreover, they might be able to make an API call to your server directly without letting those calls process through your application.

Webhooks are isolated from your application. It's only getting incoming data that your application receives. There's no way a user would be able to trigger it manually without performing the required action that triggers the webhook event.

Restrictive Use Cases

APIs are universal. You can create an API for anything you want and will also most likely use it extensively as an integral component of your application. You will absolutely need and want to use APIs for any kind of application you're building.

Webhooks have only restrictive and specific use cases. You may not even need them sometimes, and their presence is not essential for your application. Usage of webhooks mostly depends on third-party integrations you're handling in your application.

When to Use Which?

When you're evaluating which web service fits your needs best, examine what you want the web service for. If you want to trigger a custom notification to users who want to know recent updates on a trending news item, use a webhook. If you want to trigger a custom notification every time a fresh news item is pulled out, use an API. Updating the subscription status of your users is another great use case of webhooks that we have already seen.

So where should you use APIs? Well, everywhere else!

Remember, APIs will always accompany webhooks. For instance, in the previous example, when a webhook is triggered to update the payment status of the user, the webhook will eventually make an API call to update the payment status of that user in the database.

What's Next?

There's no competition between webhooks and APIs. They're both meant to solve different problems. Webhooks are an attempt to optimize your workflow where an API might add some unneeded complexity. However, they're not here to replace APIs in any way whatsoever.

I'd highly recommend you go ahead and build a small feature that lets you use webhooks alongside APIs. You could build a simple newsletter application that triggers a Slack webhook to notify you of subscribers that are waiting to hear from you. Or maybe I'll come back with another post where we actually build this and see some webhooks in action!

About the Author

This post was written by Siddhant Varma. Siddhant is a full stack JavaScript developer with expertise in frontend engineering. He’s worked with scaling multiple startups in India and has experience building products in the Ed-Tech and healthcare industries. Siddhant has a passion for teaching and a knack for writing. He's also taught programming to many graduates, helping them become better future developers.