Testing Trello Webhooks With Ngrok

1. Introduction

In this article, we are going to have a look at an example of testing Trello webhooks with Ngrok.

Testing a webhook locally is a challenging task as the localhost is not accessible over the internet and the webhooks require a URL that can be accessed outside of your network/firewall.

In this easy-to-understand tutorial, we’ll have a look at how to test the webhooks locally and easily, without much hassle.

2. What is a Webhook?

A webhook is an HTTP callback. You create a register a webhook with some external application by providing a callback URL. When something happens, the external application will send an HTTP request to the callback URL.

In this use case, we are using Trello. Whenever someone creates a new Card on Trello, we want to save that information to a file.

To achieve this, we need some way to integrate with Trello and we need some way using with Trello will notify us that a new Card has been created. Webhooks solves this problem.

We’re going to register a webhook with Trello and give it a callback URL. Whenever a new Card is created, Trello will send an HTTP POST request to the callback URL. The POST body will contain all the details of the newly created Card.

3. Register a Webhook

In order to register a Webhook, we’ll need Trello API Key and Token. You can grab yours here. Once you have the Key and Token, we need a callback URL.

In your web application, create a new endpoint in this example, we’ll create one new endpoint http://localhost:7070/webhooks/board.

We’ll expose this endpoint over HTTP GET as well as HTTP POST. The GET method is required because when we register a Webhook, Trello will do a quick check to see if it gets a 200 OK response.

The POST method is the one where we’ll do our actual work.

The Webhook registration request looks like this:

HTTP POST https://api.trello.com/1/tokens/{APIToken}/webhooks

{
    "key": "{APIKey}",
    "callbackURL": "http://localhost:7070/webhooks/board",
    "idModel":"4d5ea62fd76aa1136000000c",
    "description": "My first webhook" 
}

One thing to note here is that we cannot directly use http://localhost:7070/webhooks/board in the Webhook registration request. The reason is that the localhost is not accessible by the Trello API.

We need a mechanism to expose the localhost over the internet. Here Ngrok comes into the picture.

The idModel is the id of the Trello Board that we need to watch and its not a Webhook concern. Refer Trello documentation for more.

3.1 Exposing localhost Using Ngrok

Ngrok creates a tunnel to your localhost and serves it over a public URL.

  1. Download Ngrok from here.
  2. Extract it to your machine.
  3. Start your web server on any port, say 7070.
  4. Run ngrokhttp 7070. Ngrok will start now.
  5. Go to http://localhost:4040. This is the Ngrok UI.

Ngrok

On the Ngrok UI, you will see something like this. The URL http://78d81a9b.ngrok.io will tunnel to http://localhost:7070. This means, http://78d81a9b.ngrok.io/webhooks/board tunnels to http://localhost:7070/webhooks/board.

This solves our problem. Thus, we can simply replace localhost URL with this public URL in the call to our Webhook.

Once done, whenever we create a new Card, we’ll get HTTP POST request on http://localhost:7070/webhooks/board, which will then be forwarded to our application on localhost.

So, our updated request looks like this:

HTTP POST https://api.trello.com/1/tokens/{APIToken}/webhooks/
{
  "key": "{APIKey}",
  "callbackURL": "http://78d81a9b.ngrok.io/webhooks/board",
  "idModel":"4d5ea62fd76aa1136000000c",
  "description": "My first webhook"  
}

Fire the request and create a new Card on your Trello board. Once done, your Ngrok UI will be updated with the new request:

Ngork Post request

This request should be transferred to our web application running on the local host.

If we want to debug the same request again, simply click Replay button on the UI.

4. Conclusion

In this article, we learnt that the testing Webhooks locally poses a unique challenge. We also learnt that using Ngrok makes it pretty easy to test the Webhook callbacks.

The complete source code from this article can be found over on GutHub.

Here is the video demo.