I wanted to do some work developing some functionality against Github using Hubot, and I hit the classic challenge of attempting to develop against a webhook-centric interface: “How am I going to simulate the webhooks?”.
Fortunately I did some basic searching and stumbled across a project called Ngrok. Ngrok is a pay-what-you-want tool that allows you to expose a local server externally without all the headaches that would otherwise be necessary at the network infrastructure level.
Below follow step-by-step instructions on how to get up and going with Ngrok. Assuming your an on an OS X development machine. If you’re using another operating system most of the steps will be close but details will most likely vary.
Step 1. Sign Up With Ngrok (optional)
Incredibly it’s not actually necessary to sign-up for an Ngrok account to use their tool. If you don’t wish to signup you can simply proceed to Step 2., however, there are some nice features that are available if you do signup, such as custom subdomains and password protected tunnels. These instructions will assume you have signed up for an account, so if you skip this step your mileage may vary.
Simply proceed to https://ngrok.com/user/signup and enter your details, after signup you will be prompted to pay (only if you wish!) and then should eventually end up on a dashboard that looks something like this:
Step 2. Download Ngrok
Click on the downloading ngrok link on the dashboard (or here):
Choose the appropriate version of ngrok for your operating system:
After downloading I chose to move ngrok to my Applications folder. This is not necessary, but if you place it in a different location adjust the rest of the instructions accordingly:
Step 3. Starting Ngrok
WARNING: This will expose your local port 80 to the internet. Exercise with Caution!
Simply run the command that is shown on your dashboard in a terminal to start Ngrok. It will look something like this:
ruby-2.1.2 ➜ ~ /Applications/ngrok -authtoken 80
The authtoken is only necessary the first time you start Ngrok as it remembers it in a ~/.ngrok file for you.
After starting ngrok, you should see something like this in your terminal:
Step 3. Testing Ngrok
Ngrok creates a web interface that’s available on port 4040, and can be used to inspect packets. You can checkout it out by going to http://localhost:4040 in your browser. You should see something like this:
Ngrok has created both an http and https endpoint on the external web for your local Port 80. You can check out what happens by clicking on either link. For me, I currently have the default Apache “It works!” page running on my development machines port 80, so I see this:
So at this point I now have a tunnel open that’s redirecting an external url to a local server. To start developing against those webhooks you simply need to give them that Ngrok URL as your webhook or call back endpoint, and start building!
But wait, there’s more!
Step 4. Checkout some other cool features!
Ngroks web interface will keep a history of all the requests it proxies, including request times, request/response header, body.
It even has a “Replay” button, so you can retransmit any requests to your server. This means you can re-test any callbacks you want easily without having to drive the 3rd party system you are building against. This is a amazing feature, which will make development significantly faster by saving you the hassle of clicking-driving external products:
Conclusion
This is one of the coolest development tools I’ve seen this year, and on a pay-what-you-want model its an amazing value. If you try this out and get value from it, I highly recommend contributing back to the project. They accept paypal, so it’s easy to throw a few dollars their way. I personally think it’s well worth the recommended $25 yearly contribution.