Local Webhook Development Using Hookdeck CLI

For many developers, working with webhooks can be stressful. Typically, developers need to set up a local tunneling solution for proxying external requests to their local server, and also set up a tool for inspecting webhook payloads. The lack of proper tooling for working with webhooks in a development environment inspired us to build the Hookdeck CLI.

The Hookdeck CLI is a command line interface which provides functionality for proxying external requests to a port on your local machine and inspecting webhook payloads. Although it uses a different approach and philosophy, the Hookdeck CLI is a replacement for Ngrok and alternative HTTPS tunnel solutions. Using the Hookdeck CLI requires minimal setup, allowing developers to focus on more important parts of their webhook development workflows.

In this guide, we’ll learn how to use Hookdeck CLI to develop and test webhook integrations locally. We’ll also take a step by step approach and integrate with Dev.to webhook offering as an example.

After reading this, you will learn how to:

• Set up Hookdeck CLI
• Receive events on Localhost
• Inspect payloads on Hookdeck Dashboard

Setting Up The Local Server

To illustrate how the Hookdeck CLI simplifies local webhook development, we will integrate with Dev.to webhooks. The integration will consist of a simple server that receives webhook notifications when a specified event is triggered and prints out the notification to the console. To get started, initialize a NodeJs project and add the following lines of code in the newly created index.js file:

    const express = require("express");
    const app = express();

    app.post("/webhook", async (req, res) => {
      console.log(req.body)
      res.status(200).send("ok")
    });

    app.listen(3000, () => console.log(`App is running on port 3000`));

The simple server we just created will receive notifications from Dev.to and print the notifications to the console once we have registered Dev.to webhooks.

When registering our Dev.to webhook, we are required to provide a target URL which will receive webhook notifications. Since we are in a development mode, we will use the Hookdeck CLI to proxy external requests to our server and generate a target URL.

Working With The Hookdeck CLI

Installation
Before we can get to exploring the various rich features of the Hookdeck CLI, we need to install it onto our local computers. The method of installation will differ slightly based on the operating system your machine runs on. Various installation methods include:

• MacOS Installation
  • The Hookdeck CLI can be installed on MacOS using Homebrew. Homebrew is a package manager for MacOS. Run the following command to install the Hookdeck CLI on your Mac: $ brew install hookdeck/hookdeck/hookdeck
• Windows Installation
  • On a Windows machine, the Hookdeck CLI can be installed via the scoop package manager by running the following command: $ scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git $ scoop install hookdeck
• Linux Installation
  • Installing the Hookdeck CLI on a Linux machine requires a few more steps than other operating systems. To Install Hookdeck CLI on the Linux distro of choice:
    1. Download the latest Linux tar.gz file from https://github.com/hookdeck/hookdeck-cli/releases/latest
    2. Unzip the file: tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
    3. Navigate to the unzipped directory
    4. Run the executable: ./hookdeck

After following the steps relevant to your operating system, the Hookdeck CLI should be installed on your local machine. To test that the CLI was installed correctly, you can run the following command:

$ hookdeck version

If you have correctly installed the Hookdeck CLI, you should see the version of Hookdeck CLI you installed printed out. At the time of writing this, the latest Hookdeck version is 0.2.

Start a session
With the Hookdeck CLI installed, we need to configure it to listen for new connections and incoming requests so that our local server will be able to receive webhook notifications. Before you are able to listen for incoming requests, you need to log in to your Hookdeck account. To log in, run the $ hookdeck login command. You will be prompted to press the “Enter” key, and will then be directed to your browser where you will be authenticated and authorized to interact with the other features of the Hookdeck CLI. You can also run the $ hookdeck login command with the -i flag if you would like to manually provide an API key to authenticate.

To start a forwarding session, run the following command: hookdeck listen 3000. Notice how we use the exact port our local server runs on as an argument when running the Hookdeck “listen” command. After running this command, you will be prompted to choose an existing source or create a new source. Choose the “Create New Source” option and fill in the prompt with your source label, Devto webhooks.

The next question in the CLI prompt requires that we specify the path on our local server where webhooks should be forwarded to, which based on the server created above is the /webhook route. Fill the prompt asking for the connection label with a friendly alias for your soon to be created connection. Keep the URL provided by Hookdeck handy, as we will use it when registering our Dev.to webhook.

Awesome! We now have the Hookdeck CLI set up and listening for incoming requests.

In an event where you get stuck down the line run any of the following commands to access the Hookdeck CLI help menu:

$ hookdeck --help
$ hookdeck -h

Registering Dev.to webhooks
Now that we have successfully set up the Hookdeck CLI to listen and forward requests to our local server, we can go ahead and register the Dev.to webhook. To register Dev.to webhooks, we need to make a POST HTTP request to the /webhook route of the Dev.to API. The payload of the request to Dev.to will contain a target URL field, whose value will be the URL of our Hookdeck connection. A sample payload for the POST request to the Dev.to webhook should look similar to the JSON object below:

    {
      "webhook_endpoint": {
        "target_url": "https://events.hookdeck.com/e/src_5UbKi..."
        "source": "DEV",
        "events": [
          "article_updated"
        ]
      }
    }

After making the POST request to the Dev.to API, an output like this can be seen printed to your terminal whenever the article_update event is triggered:

Inspecting payloads
Aside from proxying external requests to a port on our local machine, The Hookdeck CLI is very useful for inspecting webhook payloads. We will be inspecting payloads received from Dev.to webhooks in the steps below:

1. Copy the inspect URL Hookdeck provides, after starting a “listen” session.
   

2. Visit the URL in the browser to view and inspect the webhook payload. The output of the payload on the Hookdeck dashboard should look similar to the image below, which makes visible the body of the webhook notification sent by Dev.to as well as the headers.
   

In Conclusion

We have learned how to set up Hookdeck CLI, proxy external requests to our local server, and inspect payloads. The Hookdeck CLI helps makes the entire process of working with webhooks locally seamless.
Interested to learn more? Follow Hookdeck where I'll be sharing tutorials and guide about webhooks!
Try Hookdeck For Free. Receive, monitor and manage all your webhooks from a single place. We handle the complexity so you can focus on building your product.

Glossary

• Source — A Source represents an API sending you a webhook, such as Shopify, Stripe, Github, etc. Each source is assigned a unique Webhook URL that can be provided to the sender.
• A Destination represents an endpoint on your own server. Hookdeck will be forwarding all webhooks received to that URL with an HTTP POST request containing the original data from the sender along with additional Hookdeck metadata.