Webhooks 101

Developers 3 min read Jul 2018 |   Author: Sinch MessageMedia

To get your creative juices flowing, let’s picture this scenario. You’ve decided to dine in at a Mexican restaurant and you’ve ordered a mouth-watering naked burrito meal. You’ve made the payment and were handed a table number. Now you patiently wait for your order to be brought to you.

A Webhook is a simple real-time notification of an event via a HTTP request to a specified URL. In the Webhooks world, the data is the order, the event is your order being made and once it is ready, the Webhook is triggered and the data is sent to the specified URL or in other words, the waiter brings your meal to the assigned table number. There is no monitoring involved as you’re certain that you will be notified once the event occurs.

Unfortunately, the system was not always this straightforward. Traditional web applications relied on a method called ‘polling’ which involved monitoring an application and checking for fresh data at certain intervals. This consisted of making frequent calls to the API and asking it “Hey do you have any new data?” and more often than not, the answer was no. As you can imagine, this approach reeked of inefficiency. Here’s a visual example of how polling works.

What are webooks

A web application implementing Webhooks will send a HTTP request to a URL when certain things happen. This can be as simple as providing your URL in a request and choosing an event that will fire the Webhook. For instance, you can use Slack’s API to add a Webhook which will notify your application when a message has been received in a channel. The URL, in this case, would be an endpoint in your application (eg: https://myapp.com/test) and the event that will trigger the Webhook would be a message received in your Slack channel. Here’s an example of how Webhooks works.

API vs Webhooks

Although these two are very different in the way they operate, there seems to be an air of confusion around them. Simply put, an API is a common interface between two different applications, an intermediary that allows two applications to talk to each other. In contrast, Webhooks are typically used to integrate two systems. An API call can be used to request data whereas a Webhook will receive data. In other words, the foundational difference between Webhooks and API calls is that the former is event-based whereas the latter is request-based.

How to use Webhooks

Surely real-time event notifications can’t be easy to implement. Or can they? Webhooks are incredibly easy to create, a lot easier than building an API although you would most likely need an API in order to consume a Webhook. Keep in mind, a Webhook is nothing but a HTTP request that is sent to a specific URL. That URL is set up to receive the body of the HTTP request and process it. So, from the server-side or the sending side, you would provide your users with the ability to submit their own URL and then send a HTTP request to that URL when some sort of event occurs. From the client-side or the receiving end, you would create a URL that is set up to receive the request. This endpoint would receive an event object in JSON or XML. This would look something like this:

{ 
  “messages”: [ 
     { 
         “content”: “My first message!”, 
         “destination_number”: “+61491570156”, 
         “callback_url”: “https://my.url/handler”, 
         “metadata”: { 
             “property1”: “value1”, 
             “property2”: “value2” 
         } 
     } 
  ] 
}

Who’s actually using Webhooks

There are many companies who rely on Webhooks for everyday operations. Some companies include Jira, eBay, and Github. Jira uses Webhooks to notify your app or web application when certain events occur in Jira. For example, you might want to alert your remote application when an issue has been updated or when sprint has been started. eBay provides its own set of useful Webhooks. For instance, it might inform you when a product is updated, an order is paid for or a refund is initiated. Github’s Webhooks system allows you to keep track of commits, trigger CI builds, or even deploy to your production server. There are thousands of other companies who are relying on Webhooks for everyday operations.

Next steps

Webhooks have already started reshaping the internet and are paving the path to real-time web experiences. They have evolved the way developers integrate applications and are an invaluable tool that is being adopted by organisations. The second part of this series talks about security in Webhooks. You can read about it over here.