Minimalist dive into webhooks

Have you ever read something and just thought: “Waouh, if I could just understand that, I could take over the world. :)”. Well I had that moment, when reading Github’s webhook page:

“Webhooks allow you to build or set up integrations which subscribe to certain events on GitHub.com. When one of those events is triggered, we’ll send a HTTP POST payload to the webhook’s configured URL. Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. You’re only limited by your imagination.”

That last line, almost possessed me for the last couple of days. I first started dreaming: “Waouh, imagine if there a bunch of websites with webhooks, your one action, could propagate on the web.”, doing all types of automations.

My first experience with this type of push events was with ifttt, one that automatically bookmarks tweets you like. Then with Google’s bot that checks whether you signed their agreement when contributing to their open source repos.

As you could imagine, I started googling stuff. Stumbled upon progruim’s talk at Google and my hunch was confirmed. This pattern is freaking awesome. Couldn’t help it but read all posts on his blog.

Then I had doubts, why something this awesome would not get recognized (popular) and went bananas on google, hacker news, you name it. All the articles I found were talking about how great/awesome webhooks were but none mentioned the actual step, nitty gritty details about how these things work.

With, shameless trials and errors, received my first successful payload that got triggered with a comment on the test’s repo. Let’s dive in:

First, we are getting a POST request from Github that will provide us the payload (data from it). That means we need a server, somehow.

Boom, that’s it. Nothing fancy or complicated.

Now you might be thinking, “time to deploy somewhere buddy” and you are right. Thought of deploying to Heroku, then realized “If this works, I’ll be messing with them real hard”. So I learned the basic use of ngrok for once. Really, you can expose whatever local server to the web right from your computer. It’s that awesome.

cd where you’ve downloaded it, then run it:

./ngrok http 3000

Then you will get a forwarding port:

Forwarding           http://xxxxxxxx.ngrok.io -> localhost:3000

You are right on the money. That link is your gateway to the www.

Then on your repo’s settings create a webhook, for this case the payload url will be: http://xxxxxx.ngrok.io/ping/github/:user/:repo/

Once you create it, Github will send you a ping. If for some reason you’re getting errors: 5xx or 4xx, keep tweaking your code or setup, while create new events: new issues, comments… You will learn a lot.

Once you successfully receive the payload, you will get a bunch of data that you can mess with in very interesting ways.

So, in conclusion, I think webhooks require a lot a of work and messing around upfront but then provides you unknown powers. Going back to Github’s point, just imagine what you could do with them...

Hopefully, I got you thinking more about them, making this post a successful webhook :). Learn more:

1. From webhooks to the evented web
2. Description to the layman
3. Webhooks, the devil in the details
4. How to safely invoke webhooks

This post is far from perfect, so provide suggestions to make it awesome.