06 Jun 2011
Webhooks are an emerging feature in many great APIs. They allow you (or rather, your applications) to avoid polling a service for data by pushing events to you as they happen. However, this aspect makes them tricky to test outside of a production-ready environment. Fortunately, there is a really simle method that makes consuming webhooks in a development environment a breeze.
Whereas most API calls are initiated by your application, webhooks originate from the API provider’s own servers. Because of this role reversal, an app’s testing environment must be publicly accessible if webhooks are being used and tested. One solution is to use a free hosting solution such as a single Heroku dyno or App Engine to temporarily run the app while you test. I did this for a while but it didn’t suit my iterative development process as every time I made a change I had to re-deploy the app. So how does one test features that require a publically visible server from behind a firewall or network gateway?
Enter localtunnel. Localtunnel is a free service that creates an SSH tunnel from your machine to the outside world using a custom url on their site. All this is done behind the scenes by a Ruby gem so you don’t know the first thing about SSH in order to get it working. Here’s how you set it up:
Open a console and install the localtunnel gem:
gem install localtunnel
If you don’t have one, set up a public/private keypair. On Linux or Mac, open a terminal and run
Accept all the defaults. On Windows it’s a bit trickier but your best bet is to install PuTTY and follow the instructions here: http://kb.siteground.com/article/How_to_generate_an_SSH_key_on_Windows_using_PuTTY.html
The first time you run localtunnel you’ll need to tell it about your public key, followed by the port you wish to forward:
localtunnel -k ~/.ssh/id_rsa.pub 3000
Each subsequent time you can just specify the port you wish to expose to the outside world:
Copy the url that is returned into your app as the base for your webhook handler addresses:
Port 3000 is now publicly accessible from http://44ea.localtunnel.com …
Register your webhooks with the service you’re using.
That’s it! You can now test webhooks or other push features to your heart’s content. When you’re done, just terminate the localtunnel process to close the connection. The one downside is that the address localtunnel provides changes each time you run it, so don’t rely on it staying the same between sessions.
Thanks for reading! If you like my writing, you may be interested in my book: Healthy Webhook Consumption with Rails
David at 10:00