Blog

Search This Blog

Loading...

Wednesday, April 11, 2012

One Webhook to Rule Them All - One URL, Millions of Possibilities

Have you ever wished the service you were using had integrations with other third party services? If it supports webhooks, I'll show you in this post how to easily integrate with any service that has an API. And no server is required.

What is a Webhook?

"The concept of a WebHook is simple. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST."

That is taken directly from webhooks.org.

The Problem with Webhooks Today

There are some great services that support webhooks (otherwise known as a callback URL): GitHub, Tender, Freshbooks, Papertrail, etc, but the problem is they usually only support a few services. This is generally because the webhook is sort of useless unless the third party also has an endpoint that can accept the webhook and understand and do something with the data it's receiving. There are some solutions to this problem:


1) If the third party has an API, you can create and run your own webhook server to accept the webhook posts, transform them, then post it to the third party API. This obviously requires a fair bit of work and also maintenance to keep it running, etc.

2) GitHub has done a really nice job of providing a solution to the problem of only being able to support a few third party services with their open source service hooks project. This allows Github to integrate with a bunch of third party services and anybody can create and contribute to it so you don't have to wait for GitHub and the third party to work it out. These basically take the GitHub payload, transform it, then post it to a third party service API and since Github is running these, you don't need to run your own server. This is awesome, but the problem is that it's only for Github.

3) I'm going to show you how you can do something very similar to the Github service hooks using IronWorker's webhook functionality, enabling you to easily do an integration between any service that supports webhooks with any service that has an API. IronWorker allows you to queue up a task for your worker by posting to a special webhook URL. The body of the post will be given to your  worker as the worker payload. You can read more details about that here or read on for a full example.

How to Create a Webhook URL that can do Anything

Let's start with an example that will take a GitHub commit webhook and post it to Hipchat. You will need an Iron.io account to run this example so if you don't have one, go get one (it's quick and free to sign up). Also note that this is example is in Ruby, but you can use other languages too. Now let's get started.

1. Create a Worker

Here's the worker code:


That should be pretty self explanatory, it just parses the GitHub webhook payload and then calls the Hipchat API. Now we need a simple config file for Hipchat info:


Modify that config file with your Hipchat API key and an existing Hipchat room name.

2. Upload the Worker to IronWorker

Now we upload that to IronWorker. Here's code to create the worker code package and upload it:


Run that with `ruby upload.rb` and it will upload the worker and print the webhook URL you'll need to add to GitHub. That's all we need to do on the IronWorker side.

3. Add the Webhook URL to Github

Now we just need to add the webhook URL to GitHub. Click Admin on your GitHub Project, then Service Hooks, then Post-Receive URLs. Here you can add the URL IronWorker URL.


Click Update Settings to save it.

4. Push Code to Github to Kick Off the Worker

That's it, now just commit and push something to your repository and check your hipchat room!



Here's the full code for this example.

You just created a very reliable, zero maintenance, no server integration between two services. Boom.


One Webhook to Rule Them All. One Webhook to Find Them. 
One Webhook to Bring Them All and In The Darkness Bind Them