A tool for debugging your webhooks locally

When developing a webhook, it's possible to simulate an HTTP request to test it locally, but this doesn't allow you to test its operation and integration in a real environment.

In this article, I'm going to show you step by step how to use ngrok to debug your webhook locally.

ngrok is a utility that allows you to create a tunnel (http, tcp, etc.) between your local machine and the ngrok.io service, thus making a port on your machine publicly available behind a temporary domain name.

Your API therefore runs locally, and as soon as you launch ngrok, you can then provide the given URL for the webhook you wish to debug!

Let's see how this works, step by step:

Download

You just need to fetch the executable that matches your system, available directly on the official website: https://ngrok.com/download

There's no installation required, it's a portable executable, which you can put anywhere in your system, although personally I gave it a spot in "Program Files".

Create an account (free)

Once installed, you'll need to create a free account on ngrok.com, because in order to provide you with a temporary domain name, the service needs to give you an API key.

Everything is free, and takes just a few seconds!

Run ngrok

Once your account is created, you'll be able to launch the executable you just downloaded, and you should see a list of commands like the one below:

You'll then need to add the API key you were given after signing up. You should see it directly on the home screen, and you'll need to add it with the following command:

ngrok config add-authtoken <token>

Be careful to run this command inside the ngrok terminal, and not in a separate terminal!

Create a tunnel

To create a tunnel, simply use the "http" command, and specify the port number your local API is running on, like this:

ngrok http 1337

And there you go, ngrok has created a link between your machine and a public URL, shown by "Forwarding".

Watch out, if you restart ngrok, the URL will necessarily change, and you'll need to provide it again to your webhook service!

And as you can see in the screenshot above, there's even a local web interface where you can see all incoming requests!