🌐 US-Proxy
dir="ltr" data-md-color-scheme="default" data-md-color-primary="" data-md-color-accent="">
Skip to content

Webhook.site CLI

The Webhook.site Command Line Interface (whcli) listens for requests to a Webhook.site URL and forwards/redirects them to your local computer or server.

For example, when a Webhook.site URL is hit, whcli will automatically forward the request to the specified URL, which can be on localhost, the local network or any other URL that can be connected to, and can automatically forward the response back to the Webhook.site URL, acting as a proxy.

Under the hood, to listen for requests, whcli uses an automatically reconnecting WebSocket that can stay active indefinitely.

Webhook.site CLI is licensed under MIT and source code is available on Github.

Star

Installation

Docker

After installing Docker, you can run Webhook.site CLI via docker run:

docker run -ti webhooksite/cli -- whcli help

Node.js

Node version 14 or greater required.

To install: npm install -g @webhooksite/cli

Then you can run e.g. whcli help

Environment variables

WH_LOG_LEVEL: Sets log level (silent, trace, debug, info, warn, error, fatal.) Defaults to info.

NODE_TLS_REJECT_UNAUTHORIZED: Set to "0" to disable SSL certificate validation (for e.g. self-signed development certificates) when using the forward command.

Variable replacement

For some commands and arguments, runtime variables can be replaced with the standard Webhook.site Custom Actions syntax (e.g. $variable$). Global Variables are not replaced.

The variables that are available are the default base variables and any variables defined in a Custom Action that was run during the request.

Commands

help: List commands

Lists commands available to the CLI.

forward: Forward requests

The forward commands acts as a bidirectional proxy, listening to incoming traffic to your Webhook.site URL, forwarding it to the target URL, and returning the response back to Webhook.site.

Parameter Environment Variable Description
--token= WH_TOKEN Required. The Webhook.site URL ID (also called token ID)
--api-key= WH_API_KEY An API key, required when using a Token that belongs to a Webhook.site account
--target= WH_TARGET Specifies URL where traffic should be forwarded.
Default: https://localhost
--listen-timeout= WH_LISTEN_TIMEOUT Amount of seconds to wait for a response from the Target URL to send back as a response for the Webhook.site URL.
Set to 0 to disable bidirectional forwarding.
Default 5. Max 10.
--keep-url When specified, disables URL merging (see below.)
--query WH_QUERY Forwards previously sent requests, filtered by a search query. When left blank, only requests sent after the command runs are forwarded.

Example

whcli forward \
  --token=1e25c1cb-e4d4-4399-a267-cd2cf1a6c864 \
  --api-key=ef6ef2f8-3e48-4f77-a54c-3891dc11c05c \ 
  --target=https://localhost:8080

Bidirectional forwarding

Per default, Webhook.site CLI waits for 5 seconds for a response from the target and forwards it to the Webhook.site URL as a response.

If you have a Web application that uses absolute paths, you should use your Webhook.site URL as a subdomain rather than a path, e.g. https://1e25c1cb-e4d4-4399-a267-cd2cf1a6c864.webhook.site rather than https://webhook.site/1e25c1cb-e4d4-4399-a267-cd2cf1a6c864.

To disable bidirectional forwarding, add parameter --listen-timeout=0.

URL merging

The request method, headers and any additional path or query string parameters added to the Webhook.site URL is forwarded on to the target. For example, if the target URL is https://example.com, sending a POST request to https://webhook.site/c33f3c3e-6018-4634-b406-65338edee460/example?query=value, the target URL will also receive a POST request on https://example.com/example?query=value.

To disable this, use the --keep-url parameter.

Docker and Localhost

When running Webhook.site CLI in Docker, to access the host machine, you can't use localhost or 127.0.0.1. Instead, you must use the special hostname host.docker.internal. More info here.

Self-signed certificates

If the target uses a self-signed certificate, you could get an error message about this. To allow self-signed certs, run whcli with the following environment variable: NODE_TLS_REJECT_UNAUTHORIZED="0"

Forwarding past requests

When the --query argument is specified, only past requests are processed, filtered by the specified query. Variable Replacement is not available for past requests.

Examples:

  • * - all requests
  • content:"foobar" - body contents containing the word foobar
  • created_at:[now-14d TO *] - date range query (in this example, all requests 14 days old and newer)

More query examples.

exec: Execute commands

Allows executing terminal commands for new incoming requests sent to your Webhook.site URL. Custom Action variables are replaced in the --command argument.

Parameter Environment Variable Description
--token= WH_TOKEN The Webhook.site URL ID (also called token ID)
--api-key= WH_API_KEY An API key, if using a Token that belongs to a Webhook.site account
--command= WH_COMMAND Specifies which command should be run

Example

whcli exec \
  --token=1e25c1cb-e4d4-4399-a267-cd2cf1a6c864 \
  --api-key=ef6ef2f8-3e48-4f77-a54c-3891dc11c05c \ 
  --command='ping $request.ip$'
Last update: May 27, 2025 11:01:09