What is a Webhook?

Your definitive guide to understanding Webhooks

Prashant Ram

Published in

codeburst

6 min readApr 1, 2018

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.

Addendum

It is important to understand that in order to implement Webhook, the client-side application must also be running some server on some port. i.e.

“client-side” application is the one making the request to the API on the “server-side”.
The “client-side” must be running a server, and the “server-side” must be running a server.
The “client-side” application makes an API request to the “server-side” server, and sends the “server-side” server a “webhook” to call once the “server-side” wants to notify the “client-side” application of some “event”.
Once the “event” occurs, and the “server-side” application calls the “webhook” url, the server that is running on the “client-side” application will “receive” that “webhook” notification.

So for example you cannot implement “Webhooks” in a pure front end application eg. React JS, Angular JS, or an iOS App, since front end-apps do not have a “server” running, and so cannot respond when the “server-side” application calls the webhook.
i.e. even if you some how had a network route to your pure front end application, since your front end application is not “listening” for any requests on any “port” (it does not have any server running to receive the webhook request), it cannot respond to the “server-side” that has invoked the webhook.

The general solution in this case is for the “front end app” or the Mobile App to implement polling the “server-side” server, since we cannot implement webhooks.

To summarize, webhooks is a mechanism for (client sider) server to (server-side) server communication, and you will need client-side to be running a server to accept the incoming webhook request that is made by the “server-side” server. So pure front end applications eg. pure React JS, AngularJS, Mobile Apps, cannot use webhooks.

References:

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

Follow me on Medium for the latest updates and posts!

✉️ Subscribe to CodeBurst’s once-weekly Email Blast, 🐦 Follow CodeBurst on Twitter, view 🗺️ The 2018 Web Developer Roadmap, and 🕸️ Learn Full Stack Web Development.