Skip to content

REST API vs. Webhook

Posted on:January 8, 2024 at 10:00 AM

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 1.

These two ideas are conceptually very close, but I get to use one of my favorite concepts when trying to explain them: Control Flow Inversion2. 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.

No workWork Available
leaderleaderworkerworkerGET /work404 NOT FOUND
leaderleaderworkerworkerGET /work200 OK {job definition}

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:

leaderleaderworkerworkerPOST /work {job definition}200 OK

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.

leaderleaderworkerworkerRegistrationPUT /worker200 OKSome delay until work is availableCallbackPOST /work {job definition}200 OK

Other registration or discovery methods are also available.


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.



  1. Thanks to the Documenting your OpenAPI Webhooks post for some ideas along the way.

  2. Wikipedia tells me that this term may be overloaded. If you find this term confusing: I’m sorry. Naming things is hard and our industry likes to give fancy names to things even if they already mean things to other groups familiar with the words. Maybe you could substitute ‘reverse the polarity’, but then you might also trigger a whole host of electrical engineers if you ever have to explain it to them!