Hookdeck CLI

Using the Hookdeck CLI, you can forward your events (e.g. webhooks) to your local web server with unlimited free and permanent event URLs. Your event history is preserved between sessions and can be viewed, replayed, or used for testing by you and your teammates.

Hookdeck CLI is compatible with most of Hookdeck's features, such as filtering and fan-out delivery. You can use Hookdeck CLI to develop or test your event (e.g. webhook) integration code locally.

Although it uses a different approach and philosophy, it's a replacement for ngrok and alternative HTTP tunnel solutions.

Hookdeck for development is completely free, and we monetize the platform with our production offering.

For a complete reference of all commands and flags, see REFERENCE.md.

hookdeck-cli-overview-v1.1.0-1080p.mp4

Installation

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

NPM

Hookdeck CLI is distributed as an NPM package:

npm install hookdeck-cli -g

To install a beta (pre-release) version:

npm install hookdeck-cli@beta -g

macOS

Hookdeck CLI is available on macOS via Homebrew:

brew install hookdeck/hookdeck/hookdeck

To install a beta (pre-release) version:

brew install hookdeck/hookdeck/hookdeck-beta

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

To install a beta (pre-release) version:

scoop install hookdeck-beta

Linux Or without package managers

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

Download the latest linux tar.gz file from https://github.com/hookdeck/hookdeck-cli/releases/latest
Unzip the file: tar -xvf hookdeck_X.X.X_linux_amd64.tar.gz
Run the executable: ./hookdeck

For beta (pre-release) versions, download the .deb or .rpm packages from the GitHub releases page (look for releases marked as "Pre-release").

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)

To use a specific version (including beta releases), specify the version tag:

docker run --rm -it hookdeck/hookdeck-cli:v1.2.3-beta.1 version

Note: Beta releases do not update the latest tag. Only stable releases update latest.

If you want to login to your Hookdeck account with the CLI and persist credentials, you can bind mount the ~/.config/hookdeck directory:

docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli login

Then you can listen on any of your sources. Don't forget to use host.docker.internal to reach a port on your host machine, otherwise that port will not be accessible from localhost inside the container.

docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli listen http://host.docker.internal:1234

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

Login with your Hookdeck account. This will typically open a browser window for authentication.

hookdeck login

If you are in an environment without a browser (e.g., a TTY-only terminal), you can use the --interactive (or -i) flag to log in by pasting your API key:

hookdeck login --interactive

Login is optional, if you do not login a temporary guest account will be created for you when you run other commands.

Listen

Start a session to forward your events to an HTTP server.

hookdeck listen <port-or-URL> <source-alias?> <connection-query?> [flags]

Flags:
  --path string             Sets the path to which events are forwarded (e.g., /webhooks or /api/stripe)
  --output string           Output mode: interactive (full UI), compact (simple logs), quiet (only fatal errors) (default "interactive")
  --max-connections int     Maximum concurrent connections to local endpoint (default: 50, increase for high-volume testing)
  --filter-body string      Filter events by request body using Hookdeck filter syntax (JSON)
  --filter-headers string   Filter events by request headers using Hookdeck filter syntax (JSON)
  --filter-query string     Filter events by query parameters using Hookdeck filter syntax (JSON)
  --filter-path string      Filter events by request path using Hookdeck filter syntax (JSON)

Hookdeck works by routing events received for a given source (i.e., Shopify, Github, etc.) to its defined destination by connecting them with a connection to a destination. The CLI allows you to receive events for any given connection and forward them to your localhost at the specified port or any valid URL.

Each source is assigned an Event URL, which you can use to receive events. When starting with a fresh account, the CLI will prompt you to create your first source. Each CLI process can listen to one source at a time.

The port-or-URL param is mandatory, events will be forwarded to http://localhost:$PORT/$DESTINATION_PATH when inputing a valid port or your provided URL.

Interactive Mode

The default interactive mode uses a full-screen TUI (Terminal User Interface) with an alternative screen buffer, meaning your terminal history is preserved when you exit. The interface includes:

Connection Header: Shows your sources, webhook URLs, and connection routing
- Auto-collapses when the first event arrives to save space
- Toggle with i to expand/collapse connection details
Event List: Scrollable history of all received events (up to 1000 events)
- Auto-scrolls to show latest events as they arrive
- Manual navigation pauses auto-scrolling
Status Bar: Shows event details and available keyboard shortcuts
Event Details View: Full request/response inspection with headers and body

Interactive Keyboard Shortcuts

While in interactive mode, you can use the following keyboard shortcuts:

↑ / ↓ or k / j - Navigate between events (select different events)
i - Toggle connection information (expand/collapse connection details)
r - Retry the selected event
o - Open the selected event in the Hookdeck dashboard
d - Show detailed request/response information for the selected event (press d or ESC to close)
- When details view is open: ↑ / ↓ scroll through content, PgUp / PgDown for page navigation
q - Quit the application (terminal state is restored)
Ctrl+C - Also quits the application

The selected event is indicated by a > character at the beginning of the line. All actions (retry, open, details) work on the currently selected event, not just the latest one. These shortcuts are displayed in the status bar at the bottom of the screen.

Listen to all your connections for a given source

The second param, source-alias 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 3000 shopify

●── HOOKDECK CLI ──●

Listening on 1 source • 2 connections • [i] Collapse

Shopify Source
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
├─ Forwards to → http://localhost:3000/webhooks/shopify/inventory (Inventory Service)
└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)

💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

2025-10-12 14:32:15 [200] POST http://localhost:3000/webhooks/shopify/orders (23ms) → https://dashboard.hookdeck.com/events/evt_...
> 2025-10-12 14:32:18 [200] POST http://localhost:3000/webhooks/shopify/inventory (45ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

Listen to multiple sources

source-alias can be a comma-separated list of source names (for example, stripe,shopify,twilio) or '*' (with quotes) to listen to all sources.

$ hookdeck listen 3000 '*'

●── HOOKDECK CLI ──●

Listening on 3 sources • 3 connections • [i] Collapse

stripe
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn01
└─ Forwards to → http://localhost:3000/webhooks/stripe (cli-stripe)

shopify
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn02
└─ Forwards to → http://localhost:3000/webhooks/shopify (cli-shopify)

twilio
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn03
└─ Forwards to → http://localhost:3000/webhooks/twilio (cli-twilio)

💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

2025-10-12 14:35:21 [200] POST http://localhost:3000/webhooks/stripe (12ms) → https://dashboard.hookdeck.com/events/evt_...
2025-10-12 14:35:44 [200] POST http://localhost:3000/webhooks/shopify (31ms) → https://dashboard.hookdeck.com/events/evt_...
> 2025-10-12 14:35:52 [200] POST http://localhost:3000/webhooks/twilio (18ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

Listen to a subset of connections

The 3rd param, connection-query specifies which connection with a CLI destination to adopt for listening. By default, the first connection with a CLI destination type will be used. If a connection with the specified name doesn't exist, a new connection will be created with the passed value. The connection query is checked against the connection name, alias, and the path values.

$ hookdeck listen 3000 shopify orders

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

Shopify Source
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)

💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

> 2025-10-12 14:38:09 [200] POST http://localhost:3000/webhooks/shopify/orders (27ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

Changing the path events are forwarded to

The --path flag sets the path to which events are forwarded.

$ hookdeck listen 3000 shopify orders --path /events/shopify/orders

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

Shopify Source
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
└─ Forwards to → http://localhost:3000/events/shopify/orders (Orders Service)

💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

> 2025-10-12 14:40:23 [200] POST http://localhost:3000/events/shopify/orders (19ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

Controlling output verbosity

The --output flag controls how events are displayed. This is useful for reducing resource usage in high-throughput scenarios or when running in the background.

Available modes:

interactive (default) - Full-screen TUI with alternative screen buffer, event history, navigation, and keyboard shortcuts. Your terminal history is preserved and restored when you exit.
compact - Simple one-line logs for all events without interactive features. Events are appended to your terminal history.
quiet - Only displays fatal connection errors (network failures, timeouts), not HTTP errors

All modes display connection information at startup and a connection status message.

Examples:

# Default - full interactive UI with keyboard shortcuts
$ hookdeck listen 3000 shopify

# Simple logging mode - prints all events as one-line logs
$ hookdeck listen 3000 shopify --output compact

# Quiet mode - only shows fatal connection errors
$ hookdeck listen 3000 shopify --output quiet

Compact mode output:

Listening on
shopify
└─ Forwards to → http://localhost:3000

Connected. Waiting for events...

2025-10-08 15:56:53 [200] POST http://localhost:3000 (45ms) → https://...
2025-10-08 15:56:54 [422] POST http://localhost:3000 (12ms) → https://...

Quiet mode output:

Listening on
shopify
└─ Forwards to → http://localhost:3000

Connected. Waiting for events...

2025-10-08 15:56:53 [ERROR] Failed to POST: connection refused

Note: In quiet mode, only fatal errors are shown (connection failures, network unreachable, timeouts). HTTP error responses (4xx, 5xx) are not displayed as they are valid HTTP responses.

Filtering events

The CLI supports filtering events using Hookdeck's filter syntax. Filters allow you to receive only events that match specific conditions, reducing noise and focusing on the events you care about during development.

Filter flags:

--filter-body - Filter events by request body content (JSON)
--filter-headers - Filter events by request headers (JSON)
--filter-query - Filter events by query parameters (JSON)
--filter-path - Filter events by request path (JSON)

All filter flags accept JSON using Hookdeck's filter syntax. You can use exact matches or operators like $exist, $gte, $lte, $in, etc.

Examples:

# Filter events by body content (only events with matching data)
hookdeck listen 3000 github --filter-body '{"action": "opened"}'

# Filter events with multiple conditions
hookdeck listen 3000 stripe --filter-body '{"type": "charge.succeeded"}' --filter-headers '{"x-stripe-signature": {"$exist": true}}'

# Filter using operators
hookdeck listen 3000 api --filter-body '{"amount": {"$gte": 100}}'

When filters are active, the CLI will display a warning message indicating which filters are applied. Only events matching all specified filter conditions will be forwarded to your local server.

Viewing and interacting with your events

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

Logout

Logout of your Hookdeck account and clear your stored credentials.

hookdeck logout

Skip SSL validation

When forwarding events to an HTTPS URL as the first argument to hookdeck listen (e.g., https://localhost:1234/webhook), you might encounter SSL validation errors if the destination is using a self-signed certificate.

For local development scenarios, you can instruct the listen command to bypass this SSL certificate validation by using its --insecure flag. You must provide the full HTTPS URL. This flag also applies to the periodic server health checks that the CLI performs.

This is dangerous and should only be used in trusted local development environments for destinations you control.

Example of skipping SSL validation for an HTTPS destination:

hookdeck listen --insecure https://<your-ssl-url-or-url:port>/ <source-alias?> <connection-query?>

Disable health checks

The CLI periodically checks if your local server is reachable and displays warnings if the connection fails. If these health checks cause issues in your environment, you can disable them with the --no-healthcheck flag:

hookdeck listen --no-healthcheck 3000 <source-alias?>

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

Running in CI

If you want to use Hookdeck in CI for tests or any other purposes, you can use your HOOKDECK_API_KEY to authenticate and start forwarding events.

$ hookdeck ci --api-key $HOOKDECK_API_KEY
Done! The Hookdeck CLI is configured in project MyProject

$ hookdeck listen 3000 shopify orders

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

Shopify Source
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)

💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

> 2025-10-12 14:42:55 [200] POST http://localhost:3000/webhooks/shopify/orders (34ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

Event Gateway

The hookdeck gateway command provides full access to Hookdeck Event Gateway resources. Use these subcommands to manage infrastructure and inspect events:

Command group	Description
`hookdeck gateway connection`	Create and manage connections between sources and destinations
`hookdeck gateway source`	Manage inbound webhook sources
`hookdeck gateway destination`	Manage destinations (HTTP endpoints, CLI, etc.)
`hookdeck gateway event`	List, get, retry, cancel, or mute events (processed deliveries)
`hookdeck gateway request`	List, get, and retry requests (raw inbound webhooks)
`hookdeck gateway attempt`	List and get delivery attempts
`hookdeck gateway transformation`	Create and manage JavaScript transformations

Examples:

# List sources and destinations
hookdeck gateway source list
hookdeck gateway destination list

# List events (processed deliveries) and requests (raw inbound webhooks)
hookdeck gateway event list --status FAILED
hookdeck gateway request list --source-id src_abc123

# List attempts for an event
hookdeck gateway attempt list --event-id evt_abc123

# Create a transformation and test-run it
hookdeck gateway transformation create --name my-transform --code "addHandler(\"transform\", (request, context) => { return request; });"
hookdeck gateway transformation run --code "addHandler(\"transform\", (request, context) => { return request; });" --request '{"headers":{}}'

For complete command and flag reference, see REFERENCE.md.

Manage connections

Create and manage webhook connections between sources and destinations with inline resource creation, authentication, processing rules, and lifecycle management. Use hookdeck gateway connection (or the backward-compatible alias hookdeck connection). For detailed examples with authentication, filters, retry rules, and rate limiting, see the complete connection management section below.

hookdeck gateway connection [command]

# Available commands
hookdeck gateway connection list      # List all connections
hookdeck gateway connection get       # Get connection details
hookdeck gateway connection create    # Create a new connection
hookdeck gateway connection upsert    # Create or update a connection (idempotent)
hookdeck gateway connection update    # Update a connection
hookdeck gateway connection delete    # Delete a connection
hookdeck gateway connection enable    # Enable a connection
hookdeck gateway connection disable   # Disable a connection
hookdeck gateway connection pause     # Pause a connection
hookdeck gateway connection unpause   # Unpause a connection

Sources and destinations

You can manage sources and destinations independently, not only inline when creating connections. Create reusable sources (e.g. Stripe, GitHub) and destinations (HTTP endpoints) that multiple connections can reference.

# List and inspect sources and destinations
hookdeck gateway source list
hookdeck gateway source get src_abc123

hookdeck gateway destination list
hookdeck gateway destination get dst_abc123

# Create a standalone destination
hookdeck gateway destination create --name "my-api" --type HTTP --url "https://api.example.com/webhooks"

See Sources and Destinations in REFERENCE.md.

Transformations

Transformations are JavaScript modules that modify requests before delivery. They are attached to connections and can add headers, transform the body, or filter events. Create, test, and manage transformations with hookdeck gateway transformation:

# Create a transformation
hookdeck gateway transformation create --name my-transform --code "addHandler(\"transform\", (request, context) => { return request; });"

# Test run transformation code (see transformed output)
hookdeck gateway transformation run --code "addHandler(\"transform\", (request, context) => { return request; });" --request '{"headers":{}}'

# List and use with connections (--transformation-name when creating connections)
hookdeck gateway transformation list

See Transformations in REFERENCE.md.

Requests, events, and attempts

Webhooks flow through Hookdeck as requests (raw inbound), then events (processed, routed), then attempts (delivery tries). Use these commands to inspect, filter, and retry:

# List requests (raw inbound webhooks) and filter by source
hookdeck gateway request list --source-id src_abc123
hookdeck gateway request get req_abc123

# List events (processed deliveries) by status
hookdeck gateway event list --status FAILED
hookdeck gateway event list --status PENDING
hookdeck gateway event get evt_abc123

# Retry a failed event or request
hookdeck gateway event retry evt_abc123
hookdeck gateway request retry req_abc123

# List attempts (individual delivery tries) for an event
hookdeck gateway attempt list --event-id evt_abc123

See Requests, Events, and Attempts in REFERENCE.md.

Manage active project

If you are a part of multiple projects, you can switch between them using our project management commands.

List projects

# List all projects
$ hookdeck project list
My Org / My Project (current)
My Org / Another Project
Another Org / Yet Another One

# Filter by organization and project name
$ hookdeck project list Org Proj
My Org / My Project (current)
My Org / Another Project

Select active project

hookdeck project use [<organization_name> [<project_name>]] [--local]

Flags:
  --local    Save project to current directory (.hookdeck/config.toml)

Project Selection Modes:

No arguments: Interactive prompt to select organization and project
One argument: Filter by organization name (prompts if multiple projects)
Two arguments: Directly select organization and project

$ hookdeck project use my-org my-project
Successfully set active project to: my-org / my-project

Configuration scope: Global vs Local

By default, project use saves your selection to the global configuration (~/.config/hookdeck/config.toml). You can pin a specific project to the current directory using the --local flag.

Configuration file precedence (only ONE is used):

The CLI uses exactly one configuration file based on this precedence:

Custom config (via --config flag) - highest priority
Local config - ${PWD}/.hookdeck/config.toml (if exists)
Global config - ~/.config/hookdeck/config.toml (default)

Unlike Git, Hookdeck does not merge multiple config files - only the highest precedence config is used.

Examples:

# No local config exists → saves to global
$ hookdeck project use my-org my-project
Successfully set active project to: my-org / my-project
Saved to: ~/.config/hookdeck/config.toml

# Local config exists → automatically updates local
$ cd ~/repo-with-local-config  # has .hookdeck/config.toml
$ hookdeck project use another-org another-project
Successfully set active project to: another-org / another-project
Updated: .hookdeck/config.toml

# Create new local config
$ cd ~/my-new-repo  # no .hookdeck/ directory
$ hookdeck project use my-org my-project --local
Successfully set active project to: my-org / my-project
Created: .hookdeck/config.toml
⚠️  Security: Add .hookdeck/ to .gitignore (contains credentials)

# Update existing local config with confirmation
$ hookdeck project use another-org another-project --local
Local configuration already exists at: .hookdeck/config.toml
? Overwrite with new project configuration? (y/N) y
Successfully set active project to: another-org / another-project
Updated: .hookdeck/config.toml

Smart default behavior:

When you run project use without --local:

If .hookdeck/config.toml exists: Updates the local config
Otherwise: Updates the global config

This ensures your directory-specific configuration is preserved when it exists.

Flag validation:

# ✅ Valid
hookdeck project use my-org my-project
hookdeck project use my-org my-project --local

# ❌ Invalid (cannot combine --config with --local)
hookdeck --config custom.toml project use my-org my-project --local
Error: --local and --config flags cannot be used together
  --local creates config at: .hookdeck/config.toml
  --config uses custom path: custom.toml

Benefits of local project pinning

Per-repository configuration: Each repository can use a different Hookdeck project
Team collaboration: Commit .hookdeck/config.toml to private repos (see security note)
No context switching: Automatically uses the right project when you cd into a directory
CI/CD friendly: Works seamlessly in automated environments

Security: Config files and source control

⚠️ IMPORTANT: Configuration files contain your Hookdeck credentials and should be treated as sensitive.

Credential Types:

CLI Key: Created when you run hookdeck login (interactive authentication)
CI Key: Created in the Hookdeck dashboard for use in CI/CD pipelines
Both are stored as api_key in config files

Recommended practices:

Private repositories: You MAY commit .hookdeck/config.toml if your repository is guaranteed to remain private and all collaborators should have access to the credentials.

Public repositories: You MUST add .hookdeck/ to your .gitignore:

# Hookdeck CLI configuration (contains credentials)
.hookdeck/

CI/CD environments: Use the HOOKDECK_API_KEY environment variable:

# The ci command automatically reads HOOKDECK_API_KEY
export HOOKDECK_API_KEY="your-ci-key"
hookdeck ci
hookdeck listen 3000

Checking which config is active:

$ hookdeck whoami
Logged in as: user@example.com
Active project: my-org / my-project
Config file: /Users/username/my-repo/.hookdeck/config.toml (local)

Removing local configuration:

To stop using local configuration and switch back to global:

$ rm -rf .hookdeck/
# Now CLI uses global config

Manage connections

Connections link sources to destinations and define how events are processed. You can create connections, including source/destination definitions, configure authentication, add processing rules (retry, filter, transform, delay, deduplicate), and manage their lifecycle.

Create a connection

Create a new connection between a source and destination. You can create the source and destination inline or reference existing resources:

# Basic connection with inline source and destination
$ hookdeck gateway connection create \
  --source-name "github-repo" \
  --source-type GITHUB \
  --destination-name "ci-system" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/webhooks"

✔ Connection created successfully
Connection: github-repo-to-ci-system (conn_abc123)
Source: github-repo (src_xyz789)
Source URL: https://hkdk.events/src_xyz789
Destination: ci-system (dst_def456)

# Using existing source and destination
$ hookdeck gateway connection create \
  --source-id src_existing123 \
  --destination-id dst_existing456 \
  --name "new-connection" \
  --description "Connects existing resources"

Add source authentication

Verify webhooks from providers like Stripe, GitHub, or Shopify by adding source authentication:

# Stripe webhook signature verification
$ hookdeck gateway connection create \
  --source-name "stripe-prod" \
  --source-type STRIPE \
  --source-webhook-secret "whsec_abc123xyz" \
  --destination-name "payment-api" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/webhooks/stripe"

# GitHub webhook signature verification
$ hookdeck gateway connection create \
  --source-name "github-webhooks" \
  --source-type GITHUB \
  --source-webhook-secret "ghp_secret123" \
  --destination-name "ci-system" \
  --destination-type HTTP \
  --destination-url "https://ci.example.com/webhook"

Add destination authentication

Secure your destination endpoint with bearer tokens, API keys, or basic authentication:

# Destination with bearer token
$ hookdeck gateway connection create \
  --source-name "webhook-source" \
  --source-type HTTP \
  --destination-name "secure-api" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/webhooks" \
  --destination-bearer-token "bearer_token_xyz"

# Destination with API key
$ hookdeck gateway connection create \
  --source-name "webhook-source" \
  --source-type HTTP \
  --destination-name "api-endpoint" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/webhooks" \
  --destination-api-key "your_api_key"

# Destination with custom headers
$ hookdeck gateway connection create \
  --source-name "webhook-source" \
  --source-type HTTP \
  --destination-name "custom-api" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/webhooks"

Configure retry rules

Add automatic retry logic with exponential or linear backoff:

# Exponential backoff retry strategy
$ hookdeck gateway connection create \
  --source-name "payment-webhooks" \
  --source-type STRIPE \
  --destination-name "payment-api" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/payments" \
  --rule-retry-strategy exponential \
  --rule-retry-count 5 \
  --rule-retry-interval 60000

Add event filters

Filter events based on request body, headers, path, or query parameters:

# Filter by event type in body
$ hookdeck gateway connection create \
  --source-name "events" \
  --source-type HTTP \
  --destination-name "processor" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/process" \
  --rule-filter-body '{"event_type":"payment.succeeded"}'

# Combined filtering
$ hookdeck gateway connection create \
  --source-name "shopify-webhooks" \
  --source-type SHOPIFY \
  --destination-name "order-processor" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/orders" \
  --rule-filter-body '{"type":"order"}' \
  --rule-retry-strategy exponential \
  --rule-retry-count 3

Configure rate limiting

Control the rate of event delivery to your destination:

# Limit to 100 requests per minute
$ hookdeck gateway connection create \
  --source-name "high-volume-source" \
  --source-type HTTP \
  --destination-name "rate-limited-api" \
  --destination-type HTTP \
  --destination-url "https://api.example.com/endpoint" \
  --destination-rate-limit 100 \
  --destination-rate-limit-period minute

Upsert connections

Create or update connections idempotently based on connection name - perfect for CI/CD and infrastructure-as-code workflows:

# Create if doesn't exist, update if it does
$ hookdeck gateway connection upsert my-connection \
  --source-name "stripe-prod" \
  --source-type STRIPE \
  --destination-name "api-prod" \
  --destination-type HTTP \
  --destination-url "https://api.example.com"

# Partial update of existing connection
$ hookdeck gateway connection upsert my-connection \
  --description "Updated description" \
  --rule-retry-count 5

# Preview changes without applying (dry-run)
$ hookdeck gateway connection upsert my-connection \
  --description "New description" \
  --dry-run

-- Dry Run: UPDATE --
Connection 'my-connection' (conn_123) will be updated with the following changes:
- Description: "New description"

List and filter connections

View all connections with flexible filtering options:

# List all connections
$ hookdeck gateway connection list

# Filter by source or destination
$ hookdeck gateway connection list --source-id src_abc123
$ hookdeck gateway connection list --destination-id dst_def456

# Filter by name pattern
$ hookdeck gateway connection list --name "production-*"

# Include disabled connections
$ hookdeck gateway connection list --disabled

# Output as JSON
$ hookdeck gateway connection list --output json

Get connection details

View detailed information about a specific connection:

# Get by ID
$ hookdeck gateway connection get conn_123abc

# Get by name
$ hookdeck gateway connection get "my-connection"

# Get as JSON
$ hookdeck gateway connection get conn_123abc --output json

# Include destination authentication credentials
$ hookdeck gateway connection get conn_123abc --include-destination-auth --output json

Connection lifecycle management

Control connection state and event processing behavior:

# Disable a connection (stops receiving events entirely)
$ hookdeck gateway connection disable conn_123abc

# Enable a disabled connection
$ hookdeck gateway connection enable conn_123abc

# Pause a connection (queues events without forwarding)
$ hookdeck gateway connection pause conn_123abc

# Resume a paused connection
$ hookdeck gateway connection unpause conn_123abc

State differences:

Disabled: Connection stops receiving events entirely
Paused: Connection queues events but doesn't forward them (useful during maintenance)

Delete a connection

Delete a connection permanently:

# Delete with confirmation prompt
$ hookdeck gateway connection delete conn_123abc

# Delete by name
$ hookdeck gateway connection delete "my-connection"

# Skip confirmation
$ hookdeck gateway connection delete conn_123abc --force

For complete flag documentation and all examples, see REFERENCE.md.

Configuration files

The Hookdeck CLI uses configuration files to store the your keys, project settings, profiles, and other configurations.

Configuration file name and locations

The CLI will look for the configuration file in the following order:

The --config flag, which allows you to specify a custom configuration file name and path per command.
The local directory .hookdeck/config.toml.
The default global configuration file location.

Default configuration Location

The default configuration location varies by operating system:

macOS/Linux: ~/.config/hookdeck/config.toml
Windows: %USERPROFILE%\.config\hookdeck\config.toml

The CLI follows the XDG Base Directory Specification on Unix-like systems, respecting the XDG_CONFIG_HOME environment variable if set.

Configuration File Format

The Hookdeck CLI configuration file is stored in TOML format and typically includes:

api_key = "api_key_xxxxxxxxxxxxxxxxxxxx"
project_id = "tm_xxxxxxxxxxxxxxx"
project_mode = "inbound" | "console"

Local Configuration

The Hookdeck CLI also supports local configuration files. If you run the CLI commands in a directory that contains a .hookdeck/config.toml file, the CLI will use that file for configuration instead of the global one.

Using Profiles

The config.toml file supports profiles which give you the ability to save different CLI configuration within the same configuration file.

You can create new profiles by either running hookdeck login or hookdeck use with the -p flag and a profile name. For example:

hookdeck login -p dev

If you know the name of your Hookdeck organization and the project you want to use with a profile you can use the following:

hookdeck project use org_name proj_name -p prod

This will results in the following config file that has two profiles:

profile = "dev"

[dev]
  api_key = "api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  project_id = "tm_5JxTelcYxOJy"
  project_mode = "inbound"

[prod]
  api_key = "api_key_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  project_id = "tm_U9Zod13qtsHp"
  project_mode = "inbound"

This allows you to run commands against different projects. For example, to listen to the webhooks source in the dev profile, run:

hookdeck listen 3030 webhooks -p dev

To listen to the webhooks source in the prod profile, run:

hookdeck listen 3030 webhooks -p prod

Global Flags

The following flags can be used with any command:

--api-key: Your API key to use for the command.
--color: Turn on/off color output (on, off, auto).
--config: Path to a specific configuration file.
--device-name: A unique name for your device.
--insecure: Allow invalid TLS certificates.
--log-level: Set the logging level (debug, info, warn, error).
--profile or -p: Use a specific configuration profile.

There are also some hidden flags that are mainly used for development and debugging:

--api-base: Sets the API base URL.
--dashboard-base: Sets the web dashboard base URL.
--console-base: Sets the web console base URL.
--ws-base: Sets the Websocket base URL.

Troubleshooting

Homebrew: Binary Already Exists Error

If you previously installed Hookdeck via the Homebrew formula and are upgrading to the cask version, you may see:

Warning: It seems there is already a Binary at '/opt/homebrew/bin/hookdeck'
from formula hookdeck; skipping link.

To resolve this, uninstall the old formula version first, then install the cask:

brew uninstall hookdeck
brew install --cask hookdeck/hookdeck/hookdeck

Developing

Running from source:

go run main.go

Generating REFERENCE.md

The REFERENCE.md file is generated from Cobra command metadata. After changing commands, flags, or help text, regenerate it:

go run ./tools/generate-reference --input REFERENCE.template.md --output REFERENCE.md

To validate that REFERENCE.md is up to date (useful in CI):

go run ./tools/generate-reference --input REFERENCE.template.md --output REFERENCE.md --check

Build from source by running:

go build

Then run the locally generated hookdeck-cli binary:

./hookdeck-cli

Testing the npm package build

To test the npm package build process locally (including the wrapper script), you can use the automated test script:

# Run the automated test script (recommended)
./test-scripts/test-npm-build.sh

The test script will:

Build all 6 platform binaries using GoReleaser
Verify the binaries directory structure
Test the wrapper script on your current platform
Verify npm pack includes all required files

Manual testing (if you prefer step-by-step):

# Install GoReleaser (if not already installed)
# Option 1: Using Homebrew (recommended on macOS)
brew install goreleaser

# Option 2: Download binary from GitHub releases
# Visit https://github.com/goreleaser/goreleaser/releases/latest

# Build all platform binaries for npm
goreleaser build -f .goreleaser/npm.yml --snapshot --clean

# Verify binaries directory structure
ls -R binaries/

# Test the wrapper script on your platform
node bin/hookdeck.js --version

# Test npm package creation (dry-run)
npm pack --dry-run

This will create the binaries/ directory with all 6 platform binaries, allowing you to test the wrapper script locally before publishing.

Testing

Running Acceptance Tests

The Hookdeck CLI includes comprehensive acceptance tests written in Go. These tests verify end-to-end functionality by executing the CLI and validating outputs.

Local testing:

# Run all acceptance tests
go test ./test/acceptance/... -v

# Run specific test
go test ./test/acceptance/... -v -run TestCLIBasics

# Skip acceptance tests (short mode)
go test ./test/acceptance/... -short

Environment setup:

For local testing, create a .env file in test/acceptance/:

# test/acceptance/.env
HOOKDECK_CLI_TESTING_API_KEY=your_api_key_here

CI/CD:

In CI environments, set the HOOKDECK_CLI_TESTING_API_KEY environment variable directly in your workflow configuration or repository secrets.

For detailed testing documentation and troubleshooting, see test/acceptance/README.md.

Testing npm package and wrapper script

The npm package includes a wrapper script (bin/hookdeck.js) that detects the platform and executes the correct binary.

Quick test (using automated script):

./test-scripts/test-npm-build.sh

Manual testing:

# Ensure GoReleaser is installed (see "Testing the npm package build" section above)

# Build all platform binaries
goreleaser build -f .goreleaser/npm.yml --snapshot --clean

# Test wrapper script on current platform
node bin/hookdeck.js version

# Verify wrapper script can find binary
node bin/hookdeck.js --help

# Test npm pack includes all files
npm pack --dry-run | grep -E "(bin/hookdeck.js|binaries/)"

Note: The wrapper script expects binaries in binaries/{platform}-{arch}/hookdeck[.exe]. When building locally, ensure all platforms are built or the wrapper will fail for missing platforms.

Testing against a local API

When testing against a non-production Hookdeck API, you can use the --api-base and --ws-base flags, e.g.:

./hookdeck-cli --api-base http://localhost:9000 --ws-base ws://localhost:3003 listen 1234

Also if running in Docker, the equivalent command would be:

docker run --rm -it \
    -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli \
    --api-base http://host.docker.internal:9000 \
    --ws-base ws://host.docker.internal:3003 \
    listen \
    http://host.docker.internal:1234

Testing the published npm package

To verify that the published npm package installs correctly and has the expected layout (wrapper script and platform binaries), use the local test script. It installs into a controlled directory (no global install) and runs the same checks as the test-npm-install CI workflow.

# Test with @latest (default)
./test-scripts/test-npm-install-local.sh

# Test with a specific version or tag
./test-scripts/test-npm-install-local.sh 1.7.1
./test-scripts/test-npm-install-local.sh @beta

Install output is written to test-scripts/.install-test/ (gitignored).

Releasing

This section describes the release process for the Hookdeck CLI.

Release Process

The release workflow supports tagging from ANY branch - it automatically detects which branch contains the tag. This means you can create beta releases directly from feature branches for testing before merging to main.

Stable Release (Preferred Method: GitHub UI)

Ensure all tests pass on main
Go to the GitHub Releases page
Click "Draft a new release"
Create a new tag with a stable version (e.g., v1.3.0)
Target the main branch
Generate release notes or write them manually
Publish the release

The GitHub Actions workflow will automatically:

Build binaries for all platforms
Create a stable GitHub release
Publish to NPM with the latest tag
Update package managers:
- Homebrew: hookdeck formula
- Scoop: hookdeck package
- Docker: Updates both the version tag and latest

Alternative (Command Line):

git checkout main
git tag v1.3.0
git push origin v1.3.0
# Then create release notes on GitHub Releases page

Pre-release from Main (General Beta Testing)

For general beta testing of features that have been merged to main:

Preferred Method: GitHub UI

Ensure main branch is in the desired state
Go to the GitHub Releases page
Click "Draft a new release"
Create a new tag with pre-release version (e.g., v1.3.0-beta.1)
Target the main branch
Check "Set as a pre-release"
Publish the release
GitHub Actions will build and publish with npm tag beta

Alternative (Command Line):

git checkout main
git tag v1.3.0-beta.1
git push origin v1.3.0-beta.1

Installing beta releases:

# NPM
npm install hookdeck-cli@beta -g

# Homebrew
brew install hookdeck/hookdeck/hookdeck-beta

# To force the symlink update and overwrite all conflicting files:
# brew link --overwrite hookdeck-beta

# Scoop
scoop install hookdeck-beta

# Docker
docker run hookdeck/hookdeck-cli:v1.3.0-beta.1 version

Pre-release from Feature Branch (Feature-Specific Testing)

For testing a specific feature in isolation before merging to main:

Preferred Method: GitHub UI

Ensure your feature branch is pushed to origin
Go to the GitHub Releases page
Click "Draft a new release"
Create a new tag with pre-release version (e.g., v1.3.0-beta.1)
Target your feature branch (e.g., feat/my-feature)
Check "Set as a pre-release"
Add notes about what's being tested
Publish the release
GitHub Actions will automatically detect the branch and build from it

Alternative (Command Line):

git checkout feat/my-feature
git tag v1.3.0-beta.1
git push origin v1.3.0-beta.1
# Then create release notes on GitHub Releases page

Installing beta releases:

# NPM
npm install hookdeck-cli@beta -g

# Homebrew
brew install hookdeck/hookdeck/hookdeck-beta

# To force the symlink update and overwrite all conflicting files:
# brew link --overwrite hookdeck-beta

# Scoop
scoop install hookdeck-beta

# Docker
docker run hookdeck/hookdeck-cli:v1.3.0-beta.1 version

Note: Only stable releases (without pre-release identifiers like -beta, -alpha) will update the latest tags across all distribution channels.

Repository Setup

GitHub Repository Settings

To maintain code quality and protect the main branch, configure the following settings in your GitHub repository:

Default Branch:

Go to Settings → Branches
Set default branch to main (if not already set)

Branch Protection Rules for main:

Go to Settings → Branches → Branch protection rules
Add rule for main branch
Enable the following settings:
- Require a pull request before merging
  - Require approvals: 1 (or as needed for your team)
- Require status checks to pass before merging
  - Require branches to be up to date before merging
  - Add status check: build-linux, build-mac, build-windows (from test workflow)
- Do not allow bypassing the above settings
- Restrict force pushes (recommended)
- Restrict deletions (recommended)

These settings ensure that all changes to main go through proper review and testing before being merged.

License

Licensed under the Apache License 2.0 license.

Name		Name	Last commit message	Last commit date
Latest commit History 569 Commits
.github		.github
.goreleaser		.goreleaser
.plans		.plans
bin		bin
docs		docs
pkg		pkg
scripts		scripts
test-scripts		test-scripts
test/acceptance		test/acceptance
tools/generate-reference		tools/generate-reference
.gitignore		.gitignore
.tool-versions		.tool-versions
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
REFERENCE.md		REFERENCE.md
REFERENCE.template.md		REFERENCE.template.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
package-lock.json		package-lock.json
package.json		package.json

License

hookdeck/hookdeck-cli

Folders and files

Latest commit

History

Repository files navigation

Hookdeck CLI

Installation

NPM

macOS

Windows

Linux Or without package managers

Docker

Usage

Commands

Login

Listen

Interactive Mode

Interactive Keyboard Shortcuts

Listen to all your connections for a given source

Listen to multiple sources

Listen to a subset of connections

Changing the path events are forwarded to

Controlling output verbosity

Filtering events

Viewing and interacting with your events

Logout

Skip SSL validation

Disable health checks

Version

Completion

Running in CI

Event Gateway

Manage connections

Sources and destinations

Transformations

Requests, events, and attempts

Manage active project

List projects

Select active project

Configuration scope: Global vs Local

Benefits of local project pinning

Security: Config files and source control

Manage connections

Create a connection

Add source authentication

Add destination authentication

Configure retry rules

Add event filters

Configure rate limiting

Upsert connections

List and filter connections

Get connection details

Connection lifecycle management

Delete a connection

Configuration files

Configuration file name and locations

Default configuration Location

Configuration File Format

Local Configuration

Using Profiles

Global Flags

Troubleshooting

Homebrew: Binary Already Exists Error

Developing

Generating REFERENCE.md

Testing the npm package build

Testing

Running Acceptance Tests

Testing npm package and wrapper script

Testing against a local API

Testing the published npm package

Releasing

Release Process

Stable Release (Preferred Method: GitHub UI)

Pre-release from Main (General Beta Testing)

Pre-release from Feature Branch (Feature-Specific Testing)

Repository Setup

GitHub Repository Settings

License