Dev Mode

Dev mode lets you receive live webhook events on your local machine without exposing it to the internet. Instead of forwarding to a public URL, FirmHook tunnels the event to the firmhook CLI agent running on your machine, which forwards it to your local server.

This is useful during development — no need for ngrok or similar tools.

How it works

External service → FirmHook ingest URL → CLI agent (your machine) → localhost:PORT/path

1. 1An event arrives at FirmHook
2. 2FirmHook detects dev mode is on and holds the event
3. 3The CLI agent (running on your machine) is connected via WebSocket
4. 4FirmHook pushes the event to the agent
5. 5The agent forwards it to your local server and reports the result back to FirmHook
6. 6FirmHook records the delivery outcome — visible in the dashboard

Step 1 — Enable dev mode on an endpoint

When creating a new endpoint

In the Create Endpoint modal, toggle Dev mode on and set a Dev forward URL — the local URL the CLI will forward events to, e.g. http://localhost:3000/webhooks.

On an existing endpoint

In the dashboard, open the endpoint and click Edit. Toggle Dev mode on and set the Dev forward URL.

The dev_forward_url set on the endpoint is used as the default by the CLI. You can override it at runtime with --forward-to without changing the endpoint.

Step 2 — Install the CLI

bash
# 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 the install:

bash
firmhook --help
firmhook version

Step 3 — Save your API key

bash
firmhook config --api-key whq_your_api_key_here

To confirm it was saved:

bash
firmhook config --show

Step 4 — Start the agent

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

For example:

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

The CLI fetches the dev_forward_url from the endpoint automatically and starts listening:

firmhook 0.1.0  |  Press Ctrl+C to stop

Connecting to wss://api.firmhook.com...
Connected. Forwarding events → http://127.0.0.1:8000/
Endpoint ID: 3eff44dc-c265-4de1-b50b-24b3e3b13eff
Forwarding → http://127.0.0.1:8000/

Override the forward URL for a session

If you want to forward to a different local URL without editing the endpoint:

bash
firmhook start acme-corp <endpoint-id> --forward-to http://localhost:4000/webhook

Run in the background

bash
firmhook start acme-corp <endpoint-id> --detach

Manage the background agent:

bash
firmhook status          # check if it's running
firmhook logs            # view recent log output
firmhook logs --follow   # stream logs in real time (Ctrl+C to stop)
firmhook stop            # stop the agent

Step 5 — Send a test event

With the agent running and your local server up, send a test event to your ingest URL:

bash
curl -X POST https://acme-corp.firmhook.com/<endpoint-id> \
  -H "X-Webhook-Api-Key: whq_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "message": "hello from firmhook"}'

The agent forwards the payload to your local server. The delivery result appears in the FirmHook dashboard under Events.

Path forwarding in dev mode

If the endpoint has path forwarding enabled (forward_path: true), the CLI appends the captured path suffix to the local forward URL — exactly as it would in production.

For example, if an event arrives at:

https://acme-corp.firmhook.com/<endpoint-id>/payments/123

And --forward-to is http://localhost:3000, the CLI forwards to:

http://localhost:3000/payments/123

The effective URL is shown in the CLI output for each event:

→ Event abc-123 (attempt 1) — forwarding to http://localhost:3000/payments/123

No extra CLI configuration is needed — path forwarding is controlled entirely by the endpoint setting.

Troubleshooting