Test Incoming Webhooks Locally with Ngrok

I'm enjoying working with hubot; I have a few different instances running for different groups. One of the things that I use hubot for is to echo activities from the source control repo, the bug tracker, the CI system, the (you get the idea) into the channel for a project. This is achieved via webhooks; a feature offered by many providers to POST information about an event to your endpoint as soon as it happens.

In this case, the webhook points to the hubot code running on heroku, which isn't an ideal place to debug a problem or fiddle about getting a message wording just right with all the fields in place. Instead, I do all that locally using the hubot and its shell adapter. How? Using Ngrok!

Ngrok Opens Localhost

Ngrok is a command you run locally, which opens a tunnel on the port you specify from your machine to the outside world. Ngrok will then make an incoming tunnel available and let you know which URL to use - ideal for allowing people to inspect development versions of your websites, or for testing incoming webhooks against a local dev platform.

Hubot runs on port 8080 by default so I start the tunnel with this command:

ngrok 8080

Ngrok gets going and presents a kind of commandline console view:

When requests start coming through, you'll see them listed here, but there are two important pieces of information that we want to grab at this point. One is the "Web Interface" URL, usually http://127.0.0.1:4040, which you can open in your browser - we'll revisit this in a bit. The most important one is the "Forwarding" URL. Requests to this endpoint will end up on your machine on the port you specified.

As an example, today I'm doing some testing with the webhooks that come in from GitHub. I didn't find that the support in existing hubot plugins was great, so I forked an existing one and added some functionality to it (you can find my plugin here, try the "joindin-hubot" branch: https://github.com/lornajane/hubot-github-repo-event-notifier). To test, I edited the webhooks on my repo to instead point to the URL ngrok gave me, so for this plugin, the webhook endpoint is now: http://42aa88bf.ngrok.com/hubot/gh-repo-events.

Then I trigger a hook to fire, and see what my hubot does. Probably, it might need a bit of fine tuning, so I can edit the code on my local machine, run the bot again, and repeat. Even better, check out the "Web Interface" link that ngrok produces - this has full details of all the requests we received and responded to. It also allows you to replay requests, so once you've triggered a webhook once you can just replay as many times as you need to (actually GitHub in particular have excellent replay features on their webhook pages, but not all providers do).

One you're happy, shut down your ngrok tunnel with Ctrl+c, and you can commit and push your changes to your live hubot. I find this technique incredibly helpful, and hopefully you do too! If you have anything to add, please leave me a comment, I think these toolchains are improving all the time so it would be great to hear how others are approaching the same problems or tools.