TL;DR

Install the CLI: brew install hooklistener/tap/hooklistener
Authenticate: hooklistener login
Start a tunnel: hooklistener tunnel --port 3000
Use the public HTTPS URL for your webhook integrations.

The Hooklistener CLI is a powerful terminal tool for webhook development. It lets you create secure tunnels to your localhost, browse and debug webhook requests in a rich TUI, and forward webhooks from your endpoints to your local server.

Whether you're integrating with Stripe, GitHub, Slack, or any other webhook provider, the CLI gives you everything you need to develop and test locally without deploying.

Installation

macOS (Homebrew)

The recommended way to install on macOS:

brew install hooklistener/tap/hooklistener

Linux / Windows / Manual

Download the latest binary for your platform from our GitHub releases page.

From Source (Cargo)

If you have Rust installed, you can build from source:

cargo install hooklistener

Verify the installation by checking the version:

hooklistener --version

Quick Start

1. Authenticate

First, log in to link the CLI to your Hooklistener account:

hooklistener login

This opens your browser where you'll approve the device. The CLI securely stores your token for future sessions.

2. Start a Tunnel

Create a public HTTPS URL that forwards to your local server:

hooklistener tunnel --port 3000

You'll get a URL like https://abc123.hook.events that you can use with any webhook provider.

3. Configure Your Webhook Provider

Copy the tunnel URL and paste it into your webhook provider's settings. For example:

Stripe: Dashboard → Developers → Webhooks → Add endpoint
GitHub: Repository → Settings → Webhooks → Add webhook
Slack: App Settings → Event Subscriptions → Request URL

Tip:Keep the tunnel running while developing. All requests to the public URL are forwarded to your local server in real-time.

Commands

The CLI provides six commands for different workflows. Click any command to see detailed documentation.

login

Authenticate with Hooklistener using a secure device code flow

tui

Launch the interactive terminal UI to browse and manage webhooks

listen

Forward webhooks from an existing endpoint to your local server

tunnel

Create a public HTTPS URL that tunnels to your local server

diagnostics

Generate a diagnostic bundle for troubleshooting and support

clean-logs

Remove old log files to free up disk space

Global Options

These options are available for all commands:

Option	Description
`--log-level <LEVEL>`	Set logging level: trace, debug, info, warn, error (default: info)
`--log-dir <PATH>`	Custom directory for log files
`--log-stdout`	Output logs to stdout in addition to files
`--help`	Show help information
`--version`	Show version information

Example with debug logging:

hooklistener --log-level debug tunnel --port 3000

Configuration

The CLI stores configuration and logs in your home directory:

Config: ~/.config/hooklistener/config.json
Logs: ~/.config/hooklistener/logs/

Environment Variables

For advanced usage or self-hosting, you can override defaults:

Variable	Description
`HOOKLISTENER_API_URL`	Base URL for API requests
`HOOKLISTENER_WS_URL`	Base URL for WebSocket connections
`HOOKLISTENER_DEVICE_PORTAL_URL`	URL for device code activation

Next Steps

Now that you've installed the CLI, explore these guides:

Slack Events API with a Hooklistener Tunnel — Set up Slack webhooks for local development
GitHub Repository Webhooks — Test GitHub webhooks locally
Stripe Webhook Integration — Debug Stripe payment webhooks

Getting Started with the CLI