Debugging with Ngrok

Ngrok is a tool allows you to expose a port on your local machine to the internet, allowing you to receive and monitor incoming requests from external sources such as webhooks. This makes Ngrok a perfect fit for debugging webhook payloads that come from Stream Chat.

Installation

Ngrok can be installed on ubuntu using apt with the following command:

$ sudo apt install ngrok

Alternatively, you can download Ngrok from their website at https://ngrok.com/. Once downloaded and unzipped, place the Ngrok executable in your applications directory.

Ngrok Configuration

Now that Ngrok is properly installed, we'll need to spin it up on port 80 using the following command:

$ ngrok http 80

Once you execute the command listed above, Ngrok will spin up a "forwarding URL" that you can use to specify in the Stream Dashboard. Now that your forwarding URL is available and online, copy the HTTPS forwarding URL as we will need it in the next step.

Dashboard Configuration

With your forwarding URL copied, login to your Stream Chat dashboard and scroll down to the webhook section. Activate the webhook and then paste your HTTPS forwarding URL in the webhook URL input . Click save to persist your settings.

Receiving Events

One of the many helpful tools that Ngrok provides is a web interface for inspecting incoming payloads. If you reference your terminal, you'll notice that there is a link for the "Web Interface" that runs on a local port – generally port 4040 if available. Navigate to http://localhost:4040 and you will see a dashboard for Ngrok.

Next, fire off an event such as a message from your chat interface to receive and inspect the payload. Once sent, the webhook will forward the payload to your Ngrok server for inspection via a POST request.

Ngrok will intermittently return a 502 Bad Gateway response. Please do not be alarmed by this as debugging with Ngrok is only for debugging purposes. In a production or staging environment, your server should return a 200 status code. Below is an example of the payload for a message:

{
    "cid": "messaging:MYH-HwwO",
    "type": "message.new",
    "message": {
        "id": "2ecb4159e50b38cfb96e8ad2c4febd69-1ea9aa03-3edf-4491-8619-b34cabd4bcfc",
        "text": "Hello!",
        "html": "<p>Hello!</p>\n",
        "type": "regular",
        "user": {
            "id": "2ecb4159e50b38cfb96e8ad2c4febd69",
            "role": "admin",
            "created_at": "2019-09-16T13:35:08.977932Z",
            "updated_at": "2019-12-04T23:28:27.744384Z",
            "last_active": "2019-12-04T23:28:27.743804Z",
            "online": true,
            "image": "https://ui-avatars.com/api/?name=nick_parsons&size=192&background=000000&color=6E7FFE&length=1",
            "name": "nick_parsons",
            "username": "nick_parsons"
        },
        "attachments": [],
        "latest_reactions": [],
        "own_reactions": [],
        "reaction_counts": null,
        "reaction_scores": {},
        "reply_count": 0,
        "created_at": "2019-12-04T23:28:35.561344Z",
        "updated_at": "2019-12-04T23:28:35.561344Z",
        "mentioned_users": []
    },
    "user": {
        "id": "2ecb4159e50b38cfb96e8ad2c4febd69",
        "role": "admin",
        "created_at": "2019-09-16T13:35:08.977932Z",
        "updated_at": "2019-12-04T23:28:27.744384Z",
        "last_active": "2019-12-04T23:28:27.743804Z",
        "online": true,
        "channel_last_read_at": "1970-01-01T00:00:00Z",
        "total_unread_count": 0,
        "unread_channels": 0,
        "unread_count": 0,
        "image": "https://ui-avatars.com/api/?name=nick_parsons&size=192&background=000000&color=6E7FFE&length=1",
        "name": "nick_parsons",
        "username": "nick_parsons",
        "channel_unread_count": 0
    },
    "watcher_count": 1,
    "created_at": "2019-12-04T23:28:35.566646131Z",
    "channel_type": "messaging",
    "channel_id": "MYH-HwwO"
}