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.

Step 1. Installation

Ngrok can be installed on macOS using Homebrew with the following command:

$ brew install --cask 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 (macOS).

Installation instructions for environments other than macOS can be found on the Ngrok website.

Create a symlink using the following commands:

# cd into your local bin directory
$ cd /usr/local/bin

# create symlink
$ ln -s /Applications/ngrok ngrok

The above symlink will allow you to run the ngrok command from any directory while in the terminal. Without the symlink, you would need to either cd into the Applications directory (or wherever you installed the executable) or reference ngrok with its full path every time.

Once installed, you can safely move onto the next step.

Step 2. 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. The output of the above command will look like this:

Now that your forwarding URL is available and online, copy the HTTPS forwarding URL as we will need it in the next step.

Step 3. 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. Your dashboard will now look similar to the image below.

Step 4. 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"
}

Events

User Presence