Introduction to Web-Hooks

You might have heard about the term web-hook somewhere in context of client-server communication, as they have become increasingly popular due to simplicity they provide compared to the alternatives. At first, the whole topic of web-hooks seems quite tricky to understand just because it flips the common notion of how we use Application Programming Interfaces (APIs). You might have read that web-hooks are also known as “reverse APIs”. I’m not sure whether you can call them as reverse APIs, but the term almost perfectly encapsulates what web-hooks stand for. In our traditional APIs, server exposes an endpoint which client can consume. For client to use this endpoint, they need to send a request to the server endpoint proactively. In case of web-hooks, an event is sent automatically to configured the endpoint automatically when a certain condition is met.

Imagine a common scenario where client sends an API request to server. The server is processing the request, but it’s gonna take some amount of time which is undefined. So in traditional sense, if client needs that response from server it’ll keep pinging server for the response in predefined time intervals. This process is known as polling. Handling these polling requests from server side increases latency and impacts throughput adversely. Consider this scenario similar to when you’re travelling and your parents call you after every 15 mins asking whether you’ve reached to the destination or not. Surely this is very irritating. A possible workaround to this situation is to tell your parents before leaving that, please don’t call me. Instead I’ll call you once I reach to the destination. This is exactly what a web-hook does.

In case of web-hooks, unlike APIs client provide their endpoint URL to server so that server can send the event to the client when processing of the request is complete. In our analogy, parent’s phone number is that endpoint URL which we need to call once event of reaching to destination occurs.

Now let’s look at a real life example where web-hooks can be used. While buying stuff online you’re directed towards a payment gateway interface. These are third party interfaces compliant with data security standards which handle payments. Say you’re shopping from amazon.in, and using Paytm as payment gateway. During checking out, you’ll be redirected to Paytm’s page for payment. You complete the payment by either credit/debit card or UPI. Once payment is done, amazon.in would require the information if this transaction was successful or not. In such situations, web-hooks are immensely helpful and pretty popular tools. Once transaction is done, Paytm will send an event to predefined URL of amazon.in to let them know about the payment status.

{
    "event" : "payment.done"
    "payment":
       {
        "transacion_id": "amz_098765421",
        "entity": "payment",
        "amount": 1000,
        "currency": "INR",
        "status": "success"
        }
}

The web-hook payload might look like above snippet. On client application, we can get event with id “payment.done”, “payment.pending” etc. In above example, we can get to know if payment was successful or not from payload.payment.status with possible values as success or failure.