Getting Started: Local Development

The HookBridge CLI (hb) lets you receive webhooks on your local machine. Paste a HookBridge URL into your webhook provider (Stripe, GitHub, etc.), run hb listen, and webhooks are forwarded to your local server in real time.

Prerequisites

• HookBridge account at app.hookbridge.io
• An API key (create one in the console)
• A local server running that accepts HTTP POST requests

Step 1: Install the CLI

See the CLI Installation guide for all options including Homebrew, binary downloads, and go install.

The quickest method on macOS or Linux:

brew install hookbridge/tap/hb

Verify the installation:

hb version

Step 2: Log In

Authenticate with your HookBridge API key:

hb login

You will be prompted to enter your API key. The CLI verifies the key and saves credentials locally. See Config File for the location on each platform.

You can also pass the key non-interactively:

hb login --api-key YOUR_API_KEY

Step 3: Start Listening

Start your local server, then run:

hb listen --port 3000

The CLI will:

1. Find or create a CLI-mode inbound endpoint in your project.
2. Print a Webhook URL — copy this into your webhook provider’s settings.
3. Connect and wait for webhooks.

HookBridge CLI v1.0.0
Endpoint: CLI Endpoint (ie_abc123)

Webhook URL: https://receive.hookbridge.io/v1/webhooks/receive/ie_abc123/sk_xyz789

Paste this URL into your webhook provider's settings.
Forwarding to http://localhost:3000
Ready. Waiting for webhooks...

Step 4: Send a Test Webhook

From another terminal, send a test request to the Webhook URL printed above:

curl -X POST "https://receive.hookbridge.io/v1/webhooks/receive/YOUR_ENDPOINT_ID/YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"id":"123"}}'

You should see the webhook arrive in your CLI output:

12:34:01  POST  →  200  89ms  application/json  (42 bytes)

Step 5: Use with a Webhook Provider

Replace the test curl with a real webhook provider:

1. Go to your provider’s webhook settings (Stripe Dashboard, GitHub repo settings, etc.).
2. Set the webhook URL to the Webhook URL from hb listen.
3. Trigger an event in the provider.
4. Watch the webhook arrive in your terminal and hit your local server.

The Webhook URL is stable across sessions — you do not need to update your provider settings each time you restart the CLI.

Inspect Mode

To view webhooks without forwarding them to a local server:

hb listen --no-forward

To see full headers and body for each webhook:

hb listen --port 3000 --verbose

Next Steps

• CLI Command Reference — All commands and flags
• How It Works — Architecture and trust model
• Inbound Overview — How inbound webhook ingestion works