What is a Webhook?

Your definitive guide to understanding Webhooks

Introduction

Web hooks are a incredibly useful and a resource-light way to implement event reactions. Web hooks provide a mechanism where by a server-side application can notify a client-side application when a new event (that the client-side application might be interested in) has occurred on the server.

Webhooks are also sometimes referred to as “Reverse APIs”. In APIs, the client-side application calls (consumes) the server-side application. Whereas, in case of web hooks it is the server-side that calls (consumes) the web hook (the end-point URL provided by the client-side application), i.e. it is the server-side application that calls the client-side application.

Webhooks operate on the concept of “event reaction” (don’t call me, I’ll call you if I have something new), and thus avoids the need for constant polling of the server-side application by the client-side application. Thus, rather than the client-side application constantly polling the server-side application to check for new events, the server-side application calls the client-side application (by invoking a client provided webhook URL) anytime the server-side has something new to report to the client.

This is the core concept of the Webhook.

Thus, with webhooks you can get push notifications when certain events happen on the server. You do not need to poll the API anymore to see if these events have happened. You can just ‘subscribe’ to an event with webhooks.

So, what exactly does a webhook look like?

In API calls the server-side application provides the client-side application with end-point URLs that the client-side application can call. Thus the server-side might expose the following API end-point URLs for a simple message board type application.

 POST /messages                                     createNewMessage
GET /messages/{messageId} readMessage
POST /messages/{messageId}/comments postComment
GET /messages/{messageId}/comments/{commentsId} readComment

These URLs are exposed by the server-side application.

Thus, If the client-side application wants to post a new message to the server, the client-side application calls (consumes),
POST /messages

Similarly, If the client-side application wants to read a comment posted against a particular message on the server, the client-side application calls (consumes),
GET /messages/{messageId}/comments/{commentsId}

Note that the messages and comments are created and stored on the server database, and read from the server database, using the server-provided APIs (end-point URLs).

In case of Webhooks, it is the client-side application that provides the server-side application with a URL to call, and the server-side application calls (consumes) that URL, when some relevant server-side event has occurred. So a webhook is simply an end-point URL provided by the client-side application to the server-side application. In case of our simple message board example it may look like this.

{  
“newCommentWebhook” : “https://clientdomain.com/webhook/newcomment" }

Thus, a webhook is nothing but a simple client-side provided end-point URL. This end-point URL has to be passed by the client-side application to the server-side application at some point prior to the webhook call by the server-side.

Let’s say we want the server-side application to notify the client-side application whenever a new comment has been posted against a particular message. In this case, whenever a new comment is posted to the server-side database, the server-side application should (after posting the comment to the database) call the above webhook URL, to let the client know that a new comment is available. Thus, using webhooks, the server-side can notify the client-side of a relevant event (i.e. a new comment has been posted).

From an implementation perspective, the server-side application has to design their API end-points such that there is some placeholder parameter, that allows the client-side applications to pass them the webhook URL. This can be be done by the server-side API “request body” having a parameter for web hook URLs.

Secondly, the server-side application should have some mechanism of storing the client provided web hook end-point, so that it can be called by the server-side when required. Thus in our example the server-side API request body should have some parameter, where the client-side application can include their web hook URL.

Using webhooks for notifications vs. delivering payloads

There is a debate on whether webhooks should be using simply as a notification mechanism, or its payload should also include relevant data. While it is possible to pass payload data within the body of the webhook, to improve scalability and reliability it is a good practice to keep the webhooks light-weight. Webhooks although technically can carry payload, are only a callback mechanism, and primarily should as a signal for change in state.

Here is an interesting article on “Your webhooks endpoint should do almost nothing” — by jsneedles

Once notification of the change of state is received, separate secure API interface calls can be invoked from the client-side application, to receive the actual payload. This separation of concerns allows improved scalability and reliability of the overall API integration.

Resources

The following site allows you to test the concept of webhooks https://webhook.site/ . It generates a unique test webhook URL that can be called by your application to test the callback (notification) feature of the webhook.


Found this post useful? Hit the 👏 button below to show how much you liked it! :)

Read Next: 
The Microservices Approach to React Native Mobile Application Development

Like what you read? Give Prashant Ram a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.