firmhook 0.2.1

Forward live webhook events to localhost — instant public tunnel or full dev mode with retries and logs

firmhook

The official CLI for FirmHook — a webhook monitoring and delivery platform.

The CLI gives you two ways to receive webhooks on your local machine:

	firmhook listen	firmhook start
Account required	No	Yes
API key required	No	Yes
Events stored in dashboard	No	Yes
Retries on failure	No	Yes
Response returned to provider	Yes	No
Best for	Quick testing, demos, no-account situations	Active development against a configured endpoint

---

Installation

# Recommended — isolated install, firmhook available on PATH immediately
uv tool install firmhook

# Or with pipx
pipx install firmhook

# Or with pip
pip install firmhook

Verify:

firmhook --help
firmhook version

Requires Python 3.9+.

---

Instant Tunnel — firmhook listen

Get a public URL in one command. No account, no API key, no configuration.

firmhook listen 3000

Output:

firmhook 0.2.0  |  Press Ctrl+C to stop

  Tunnel URL:  https://api.firmhook.com/tunnel/a3f2c1d4-...
  Forwarding:  http://localhost:3000

  Ready. Waiting for requests... (Ctrl+C to stop)

→ POST    http://localhost:3000  [application/json]
← 200  (42ms)

Paste the Tunnel URL into any webhook provider. All incoming requests are forwarded to your local server in real time. The actual response from your server is returned to the provider — webhook providers that validate the response (e.g. Stripe, GitHub) work correctly.

The tunnel lives as long as the CLI is running. Closing it (Ctrl+C) immediately invalidates the URL.

Options

firmhook listen <port> [--forward-to <url>]

Argument	Description
port	Local port to forward requests to
--forward-to, -f	Override the full forward URL (default: http://localhost:<port>)

Examples

# Forward to localhost:3000
firmhook listen 3000

# Forward to a specific path on localhost
firmhook listen 3000 --forward-to http://localhost:3000/webhooks

# Forward to a different local service
firmhook listen 3000 --forward-to http://127.0.0.1:4000/events

---

Dev Mode — firmhook start

For active development. Events are stored in the FirmHook dashboard with full history, retries, delivery logs, and AI-assisted error explanations.

Setup

1. Create a FirmHook account at firmhook.com.

2. Enable dev mode on an endpoint — in the dashboard, open an endpoint and toggle Dev Mode on. Set a Dev Forward URL (e.g. http://localhost:3000/webhooks).

3. Save your API key:

firmhook config --api-key fhk_your_api_key_here

4. Start forwarding:

firmhook start <org-slug> <endpoint-id>

For example:

firmhook start acme-corp b338f02c-e8b1-4dd5-93ad-0cba72f23ffe

The CLI fetches the dev_forward_url from the endpoint automatically. Events from FirmHook are forwarded to your local server as they arrive.

Options

firmhook start <org-slug> <endpoint-id> [--forward-to <url>] [--api-key <key>] [--detach]

Flag	Description
--forward-to, -f	Override the local URL for this session (does not update the endpoint)
--api-key	Use a specific API key instead of the saved one
--detach, -d	Run the agent in the background

Background mode

# Start in background
firmhook start acme-corp <endpoint-id> --detach

# Check if it's running
firmhook status

# View recent log output
firmhook logs

# Stream logs in real time
firmhook logs --follow

# Stop the background agent
firmhook stop

---

All commands

firmhook listen <port>        Open a public tunnel URL and forward requests to a local port
firmhook start <org> <id>     Connect to a FirmHook endpoint and forward events to localhost
firmhook config               Save your API key
firmhook status               Show whether the background agent is running
firmhook logs                 Print recent agent log output
firmhook stop                 Stop the background agent
firmhook version              Print the firmhook version

---

How it works

Instant tunnel

Webhook provider
      │
      ▼
POST https://api.firmhook.com/tunnel/{session_id}
      │
      ▼  Redis pub/sub
      │
      ▼
WebSocket  wss://api.firmhook.com/ws/tunnel/{session_id}
      │
      ▼
firmhook CLI  →  HTTP  →  localhost:<port>
      │
      ▼  ack (status + body)
      │
      ▼
Response returned to webhook provider

Dev mode

Webhook provider  →  FirmHook ingest URL
                           │
                       PostgreSQL (event stored)
                           │
                       Celery worker
                           │  Redis pub/sub
                           ▼
                      firmhook CLI  →  localhost:<port>
                           │
                       Delivery recorded in dashboard

---

Configuration

The CLI stores settings in ~/.firmhook/config.json.

# Save your API key
firmhook config --api-key fhk_your_key

# Show the saved API key
firmhook config --show

---

Changelog

0.2.1

• Added project URLs (homepage and source) to package metadata

0.2.0

• Added firmhook listen <port> — instant public tunnel, no account or API key required
• Server URL is now always api.firmhook.com and is no longer user-configurable

0.1.0

• Initial release — config, start, stop, status, logs, version commands