Using The Hookdeck CLI

Using the Hookdeck CLI, you can forward your webhooks to your local webserver. Although it uses a different approach and philosophy, it's a FREE replacement for ngrok and alternative HTTP tunnel solutions when working with webhooks.

  • Use Hookdeck CLI to develop and test your webhook integration code locally.
  • Use Hookdeck CLI to troubleshoot integrations without interfering with your production setup. Hookdeck will copy your webhooks and deliver them to your local server.
  • Your webhook history is preserved between sessions and can be viewed, replayed, or used for testing by you and your teammates.

For a complete reference, see the CLI reference

cli demo


Installation

Hookdeck CLI is available for macOS, Windows, Docker, and Linux for distros like Ubuntu, Debian, RedHat, and CentOS.

macOS

Hookdeck CLI is available on macOS via Homebrew:

brew install hookdeck/hookdeck/hookdeck

Windows

Hookdeck CLI is available on Windows via the Scoop package manager:

scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
scoop install hookdeck

Linux or without package managers

To install the Hookdeck CLI on Linux without a package manager:

  1. Download the latest Linux tar.gz file from https://github.com/hookdeck/hookdeck-cli/releases/latest
  2. Unzip the file: tar zxvf hookdeck_X.X.X_linux_x86_64.tar.gz
  3. Run the executable: ./hookdeck

Docker

The CLI is also available as a Docker image: hookdeck/hookdeck-cli.

docker run --rm -it hookdeck/hookdeck-cli version
hookdeck version x.y.z (beta)

Usage

Installing the CLI provides access to the hookdeck command.

hookdeck [command]

# Run `--help` for detailed information about CLI commands
hookdeck [command] help

Commands

Login

Log in with your Hookdeck account.

Listen

Start a session to forward your webhooks to a local HTTP server.

hookdeck listen <port> <source-name?> <connection-query?>

Hookdeck works by routing webhooks received to a source (ie: Shopify, Github, etc.) to its defined destination (by connection). The CLI allows you to receive webhooks for any given connection and forward them to your localhost at the specified port.

For new accounts, the CLI will prompt you to create your first source.

Each source is assigned a Webhook URL, which you can use to receive webhooks. Each CLI process can listen to one source at a time.

The port param is mandatory. Webhooks will be forwarded to http://localhost:$PORT/$DESTINATION_PATH

When using a guest account the console will print a link for you to login into the dashboard. Open that link in your browser before opening the other links printed by the command

Listen to all your connections for a given source

The second param, source-name is used to select a specific source to listen on. By default, the CLI will start listening on all eligible connections for that source.

$ hookdeck listen 5000 shopify

╭ Shopify ───────────────────────────────────────────────────────────────╮
│                                                                        │
│  🔌 Webhook URL: http://localhost:5000/e/src_dgRnekOhKKZe7KqyXK88Uajr  │
│                                                                        │
╰────────────────────────────────────────────────────────────────────────╯
Inventory Service forwarding to /webhooks/shopify/inventory
Orders Service forwarding to /webhooks/shopify/orders

👉  Inspect and replay webhooks: https://dashboard.hookdeck.com/events/cli

⣾ Getting ready...

Listen to a subset of connection

The 3rd param, connection-query can be used to filter the list of connections the CLI will listen to. The connection query can either be the connection name or the path

$ hookdeck listen 5000 shopify orders

╭ Shopify ───────────────────────────────────────────────────────────────╮
│                                                                        │
│  🔌 Webhook URL: http://localhost:5000/e/src_dgRnekOhKKZe7KqyXK88Uajr  │
│                                                                        │
╰────────────────────────────────────────────────────────────────────────╯
Inventory Service forwarding to /webhooks/shopify/inventory

👉  Inspect and replay webhooks: https://dashboard.hookdeck.com/events/cli

⣾ Getting ready...

Viewing and interacting with your webhooks

Webhooks logs for your CLI can be found at https://dashboard.hookdeck.com/events/cli. Events can be replayed or saved at https://dashboard.hookdeck.com/bookmarks.

Version

Print your CLI version and whether or not a new version is available.

hookdeck version

Completion

Configure auto-completion for Hookdeck CLI. It is run on install when using Homebrew or Scoop. You can optionally run this command when using the binaries directly or without a package manager.

hookdeck completion