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:

Screenshot from 2015-03-11 08:17:25

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, 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.

Screenshot from 2015-03-11 08:36:36

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).

Screenshot from 2015-03-11 08:40:17

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.

One thought on “Test Incoming Webhooks Locally with Ngrok

  1. Good article! I love ngrok and I’ve used it for a similar project where events in github drive the status of JIRA tickets (branch opened = in progress, pull request opened = in qa, pull request merged = done, etc.) I’ve also found ngrok useful as a workaround for http requests being made from an https page if CORS is not an option (since ngrok gives you both https and http for the same tunnel).

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.