Local development

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

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.

npm install -g hostwh
hostwh login

hostwh forward http://localhost:3001/webhooks

  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

forward options

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.

npm install -g hostwh
hostwh login

hostwh create

  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>

  It starts paused: its URL rejects every event until you activate it in the dashboard.
  To start forwarding: hostwh listen a1b2c3d4 --forward http://localhost:3001

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

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

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

listen --forward options

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.

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.

A local server behind a public URL

hostwh expose is the other kind of tunnel: instead of bringing webhooks to your machine, it gives a server on your machine a public URL — for an AI Node's tunnel tools, a Voice Agent's tunnel section, or a self-hosted model. Pass --id to keep the same URL across restarts:

hostwh expose http://localhost:3000 --id my-app

The CLI prints the public URL, https://hwtunnels.com/t/<tunnel-id>/. A request to it goes through the CLI to your server, and your server's answer comes back with its status and body — except a 502: Cloudflare, in front of hwtunnels.com, replaces it with its own page, so answer 503 if whoever calls needs to read the body. Set-Cookie is dropped, and the answer carries Content-Disposition: attachment, a sandbox Content-Security-Policy and X-Content-Type-Options: nosniff; the bytes don't change, so they only matter in a browser.

When the tunnel can't answer

When the request can't get an answer from your server, the tunnel answers 503 with JSON — { "error": "…", "code": "…" } — and Cache-Control: no-store. Not a 502: Cloudflare, in front of hwtunnels.com, replaces a 502 with its own page, and the reason would never reach whoever called. Read code; error is for people and its wording can change.

A 500 with tunnel_proxy_failed is different: the failure was in HostWebhook, not in the tunnel or your server.