Local development · Preview
From a captured webhook to your local handler.
Your provider sends a test event to a temporary bucket. The CLI subscribes to its live stream and forwards new captures from your machine to your development app. No inbound port or server-side forwarding required.
Run the local package
Requires Node.js 22 or later and a checkout containing the CLI. This preview is not published to npm. Do not run a bare npx webhooktest command: package ownership and publication are pending.
From the repository root, start your app on port 3000, then run this in a private interactive terminal:
npx --yes --package ./cli webhooktest listen --forward localhost:3000The CLI creates a bucket and shows its private webhook URL. Configure a synthetic provider event to use that URL. Wait for Connected before sending. For a local API checkout, add --api http://127.0.0.1:3001. The API must include the raw replay migration.
To attach instead, supply the bucket ID using WEBHOOKTEST_BUCKET in your private environment. Do not put capabilities in command-line flags, shell history, CI logs, screenshots, or shared terminal recordings. Creation is refused when output is redirected.
What arrives locally
Original method, raw body bytes, escaped path suffix and query string. A target path prefix is prepended. Signatures and authorization headers are retained; Host and Content-Length are rebuilt. Cookies, hop-by-hop and proxy headers are removed. CONNECT and TRACE are refused. Redirects are not followed.
Only localhost (pinned to 127.0.0.1), 127.0.0.1 and ::1 are accepted. Use HTTP or trusted HTTPS; TLS verification stays enabled. Body signatures can be checked locally; URL-bound signatures may need the original public URL in your handler configuration.
A replay tool, not a tunnel
Local responses are not returned to the original sender. The provider receives the bucket’s configured response. Terminal output shows local status and latency, never request or response bodies.
Existing captures are skipped at startup. SSE reconnects and reconciles retained history, but retention can remove missed events. Deduplication lasts only for this process; a local error or timeout is not retried because delivery may already have happened. Restart establishes a new baseline, not durable recovery.
Keep the test boundary small
Anyone who knows your webhook URL can cause requests to your local handler while listening. Use a dedicated development service, synthetic data and test credentials—not admin endpoints or production secrets. Payloads still pass through the hosted inspector. The CLI writes no capability files or analytics, but your app may log forwarded headers and bodies.
Ctrl+C stops forwarding without deleting the bucket. Remove the provider destination and delete the bucket in the inspector when finished. Deleted buckets stop the CLI; 429 stream limits trigger a delayed reconnect. Old captures without raw replay data are skipped. The CLI stops at its bounded session history limit rather than risking duplicate side effects.