How-Tos: WebHooks

Imagine you went fishing with a giant net. You cast it and pull it back up. Nothing. This is not a very fun way of fishing because you are committing so much manpower and energy to something while not knowing if the method would return any results. Instead, if you used a line with a fishing hook, you can just leave the hook in the waters without you putting much effort into it. This way, as soon as a fish bites, you know instantly and you reel it in.

Similarly in the world of REST APIs, webhooks are saviors in knowing when an event has happened. Imagine you continuously asking a server if there is the data you're looking for. This consumes so much energy and resources on your side (and the server's side) for no reason since you aren't getting what you want 99% of the time. Instead, a better implementation would be opening an endpoint to accept data to which the server will send the data to whenever it's available.

Definitions

Webhooks are actually very simple from the top-level perspective. You open an endpoint on your server and create a "subscription" with the server you're trying to get data from. Once the server accepts the request, it would start sending data for the "subscription" you made whenever it's available.

The server you are allowing webhook requests from would typically use some sort of security system to make sure the events you receive on that endpoint were indeed from them. Everyone does this differently, it could be in the form of a secret encoded hash from the payload, or maybe only whitelisted IPs can send to the webhook.

Usage

Let's set up a quick server and see how webhook works. To do this, I would need to:

Set up a local server
Expose an endpoint to accept data from a POST request.

To set up the simple server, I will be using Flask in python.

This is it... That's all you need! This simply starts a server locally using the 8080 port. Ideally, you would want something more complicated than this for a server but this will do for now to test webhooks.

Next, we need to create a route for the server to send data to:

Right now, all we do is print the data sent to the endpoint: http://localhost:8080/terra/data. In practice, you would take this data and process it in a way thats useful for you.

Now, if I start the server, (i.e running the whole file), I would have an endpoint http://localhost:8080/terra/data exposed and ready to accept "POST" requests from anyone (who is using the same network as I am, because this server only runs locally on my computer right now).

As you see, we do not ping the server whenever we want to see if there's new data, but rather we wait for the server to send us data to this endpoint. This is the webhook.

We can simulate a post request to this endpoint as if the server has new data to send to this webhook:

On the server logs when this is executed:

The function assigned to the endpoint executed and printed the payload.

Hook it up

It's time... if you are running a backend server, you should definitely start looking for possible ways webhooks can be used to remove polling.

Other than Terra, many APIs out there actually provide ways to get data through webhook:

If you use Github, they have a service to tell you when pull requests are made, when reviews are done, when pull requests are closed, etc.
If you use Stripe as a payment method, they send you a webhook when someone pays.
Youtube also allows you to subscribe to webhooks where you are told when for example a new video is uploaded by a certain YouTuber or when the video's title has been updated.

Next time you see an API allowing Webhook integration, don't skip on it! It may save you a lot of time and resources.