Local development

Receive real webhooks on your local machine — no public URL, no ngrok, no firewall rules.

✦Similar to the Stripe CLI, the HostWebhook CLI creates a secure tunnel from our servers to your localhost. The difference: it works with any webhook source — Stripe, GitHub, Shopify, or your own services.

How it works

The CLI opens a persistent WebSocket connection to HostWebhook. Incoming webhooks are held on our side, sent to the CLI over that connection, and the CLI forwards them as a regular HTTP POST to your local server. The response travels back the same way, so HostWebhook records the real status code and latency.

All retry logic, signature verification, and event history work exactly as in production — the only difference is the last hop goes to localhost instead of a public URL.

Option A — Ephemeral tunnel (fastest)

No setup required. hostwh forward creates a temporary webhook, gives you an ingress URL, and deletes the webhook automatically when you press Ctrl+C.

Install the CLI and log in

npm install -g hostwh
hostwh login

Start the tunnel

hostwh forward http://localhost:3001/webhooks

You'll immediately see a unique ingress URL:

  Creating temporary webhook...

  Ingress URL  https://api.hostwebhook.com/in/whk_abc123...

  Copy this URL into Stripe, GitHub, or any webhook provider.

  Tunnel active → http://localhost:3001/webhooks  press Ctrl+C to stop and delete

Paste the ingress URL into your webhook source

Copy the ingress URL and configure it in Stripe, GitHub, or any service sending you events. Webhooks will start arriving in your terminal immediately.

Stop the tunnel — webhook is auto-deleted

Press Ctrl+C. The CLI deletes the temporary webhook automatically — nothing left to clean up.

ℹIf the process is killed forcefully (e.g. kill -9), the webhook remains under the name forward-<8chars> and can be deleted with hostwh delete <id> or from the dashboard.

forward options

Flag	Description
--show-payload	Print the full JSON payload for each event
--show-headers	Print forwarded request headers

Option B — Persistent tunnel

Use hostwh listen --forward when you want to reuse the same ingress URL across sessions — for example, a Stripe webhook you configured once and don't want to update.

Install the CLI and log in

npm install -g hostwh
hostwh login

Verify the installation with hostwh --version.

Create a webhook

hostwh create

The CLI prompts for each field, then prints the Ingress URL:

  Name: my-app
  Target URL: https://myapp.com/webhooks
  Description (optional):
  Max retries [3]:

  ✔ Webhook created  a1b2c3d4

  Ingress URL  https://api.hostwebhook.com/in/<token>

  To start forwarding: hostwh listen a1b2c3d4 --forward http://localhost:3001

ℹSet the Target URL to your production address. While the tunnel is active, all traffic is intercepted by the CLI and sent to --forward instead. When you disconnect, traffic resumes to the Target URL automatically.

Give the ingress URL to your webhook source

Paste the ingress URL in the webhook settings of Stripe, GitHub, or any other provider. You only do this once — the same URL works in both local development and production.

Start the tunnel

hostwh listen <webhook-id> --forward http://localhost:3001/webhooks

  HostWebhook  my-app  a1b2c3d4
  Tunnel active → http://localhost:3001/webhooks  press Ctrl+C to stop

  12:34:01  tunnel  a1b2c3d4  http://localhost:3001/webhooks  HTTP 200  143ms

Trigger a test event

macOS / Linux

curl -X POST https://api.hostwebhook.com/in/<token> \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"hello": "world"}}'

Windows (PowerShell)

Invoke-WebRequest -UseBasicParsing `
  -Uri "https://api.hostwebhook.com/in/<token>" `
  -Method POST `
  -Headers @{"Content-Type"="application/json"} `
  -Body '{"event": "test", "data": {"hello": "world"}}'

A successful response is 202 Accepted. Check the CLI output and your local server — both should show the request.

listen --forward options

Flag	Description
-f, --forward <url>	Forward events to this local URL
--show-payload	Print the full JSON payload for each event
--show-headers	Print forwarded request headers

Observe mode (no forwarding)

Watch events in real-time without forwarding them anywhere — useful for debugging or monitoring a staging environment:

hostwh listen <webhook-id>

Going to production

When you're ready to deploy, just stop the CLI. HostWebhook will automatically fall back to delivering webhooks directly to the Target URL configured on your webhook. No code changes, no configuration updates — the ingress URL you gave to Stripe or GitHub stays the same.

✦The tunnel is exclusive: while the CLI is connected, 100% of traffic goes to your local machine. As soon as you disconnect, traffic resumes to the production Target URL with normal retry behavior.

Verifying signatures locally

The CLI forwards the real X-Webhook-Signature header, so your signature verification code works exactly as it will in production. You can test your HMAC logic against real payloads without any mocking. See Verifying signatures for implementation examples.