REST API vs. Webhook

At work recently I was asked, “What’s the difference between a REST API and a Webhook?” I had an immediate gut feeling for the answer, but I couldn’t put it into words right away. So I spent a little time getting my ideas in line in my head and figuring out how to describe this clearly and concisely ¹.

These two ideas are conceptually very close, but I get to use one of my favorite concepts when trying to explain them: Control Flow Inversion². But let’s start at the beginning:

What is a REST API call?

Imagine a system that has two components, let’s call them leader and worker.

In this system, there may be many workers, but for our example, we will only look at one. The leader has implemented a REST API that allows a worker to check in a see if there is any work for them to do.

After the initial call, the worker is in control of when to request more work again. If there is work, then maybe another call is made immediately upon completing the first job. If there is no work, maybe it is after some delay to avoid inundating the leader with requests when work does not arrive very frequently. It doesn’t matter for the example though, because the worker controls this logic and pulls new work to itself. The leader only responds to calls it receives.

What is a Webhook?

Now it is time to invert the control! Let’s look at the system again, but this time instead of the worker controlling when to ask for work, the leader ‘proactively’ tells the worker that a job is available:

In this design, the worker implements a REST API that receives work definitions. That is not a typo - there is also a REST API here! The difference is in who controls when the call is made. In the first example, it was the worker, but now it is the leader. If the worker receives a message that a job is available, it can return a 200 OK message and accept the job or return some other error indicating that it cannot at the moment. The leader pushes jobs to the workers, the worker only responds to calls it receives.

A little dose of the real world

You might be wondering “How does the leader know what workers are available?” This is a very good question to consider. In the pull-based method, all of the workers only need to know of a single leader URL. The push-based model requires the leader to be aware of all available workers. There are many ways to accomplish this, and some might be screaming ‘PubSub Queues’ at this point (but that is a different topic altogether).

In this system, you could have a bit of a hybrid setup where workers register and provide an endpoint to call when work is available for them.

Other registration or discovery methods are also available.

Conclusion

Hopefully, this toy example of a job distribution setup helps solidify the idea: REST APIs are pull-based, and Webhooks are push-based. Real-world implementations have a lot of variation based on other aspects of the larger system in which it exists. It is also important to note that neither of these options is inherently better than the other. Some designs may optimally run with the pull methods and others may benefit from push options.

Footnotes