Update docs

webhooksite · Jul 15, 2024 · 94a9ec6 · 94a9ec6
1 parent eaa0af3
commit 94a9ec6
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 23 deletions.
diff --git a/docs/api/requests.md b/docs/api/requests.md
@@ -240,6 +240,39 @@ Currently only the `note` field can be updated (max 10.000 characeters).
 
 `200 OK`
 
+
+## Set Response
+
+* Can require authentication.
+
+**PUT** `/requests/:token_id/requests/:request_id/response`
+
+Dynamically sets a response for a specific Webhook.site URL request when the Token has a `listen` property greater than `0`. Used for Webhook.site CLI dynamic response forwarding.
+
+The data of the `content` parameter must be base64-encoded.
+
+#### Request
+
+```json
+{
+  "content": "SGVsbG8gd29ybGQK",
+  "status": 200,
+  "headers": {
+     "Content-Type": "text/plain"
+  }
+}
+```
+
+#### Response
+
+`200 OK`
+
+```json
+{
+   "status": true
+}
+```
+
 ## Download request file
 
 * Can require authentication.

diff --git a/docs/api/tokens.md b/docs/api/tokens.md
@@ -12,12 +12,13 @@ Simply, the token ID is the part after `https://webhook.site/` in the URL, or be
 
 **POST** `/token`
 
-After creating a token, the URL at `https://webhook.site/{token.uuid}` becomes accessible, emails can be sent to `{token.uuid}@emailhook.site`, and DNS queries can be sent to `*.{token.uuid}.dnshook.site`.
+After creating a token, URLs at `https://webhook.site/{token.uuid}` and `https://{token.uuid}.webhook.site` become accessible, emails can be sent to `{token.uuid}@emailhook.site`, and DNS queries can be sent to `*.{token.uuid}.dnshook.site`.
 
 * `default_status` (int, 200-599, default 200) sets the default response status of the URL
 * `default_content` (string) sets the default response content of the URL
 * `default_content_type` (string, default `text/html`) sets the default response content type of the URL (to set other headers, take a look at the [Modify Response](/custom-actions/action-types.html#modify-response) action.)
-* `timeout` (int) waits an amount of seconds before returning the response, max 30. Intended for testing timeouts, requests to tokens with timeouts are rate limited; a high timeout value will incur a lower rate limit.
+* `timeout` (int) amount of seconds to sleep before returning the response, max 30. Intended for testing timeouts, requests to tokens with timeouts are rate limited; a high timeout value will incur a lower rate limit.
+* `listen` (int) amount of seconds to listen for a response from the Set Response endpoint. `0` to disable, max `10`. Default `0`.
 * `expiry` (int) amount of seconds until token auto-expiration. Max value (and default for non-upgraded URLs) is 604800 (one week). Intended for e.g. automated testing pipelines. Leave out or set to `null` to disable.
 * `request_limit` (int) - limits the request history amount from 1 to 10000 (default)
 * `cors` (bool) set to true will add CORS headers to the request so browsers will send cross-domain requests to the URL

diff --git a/docs/cli.md b/docs/cli.md
@@ -32,16 +32,9 @@ Then you can run e.g. `whcli help`
 
 ## Environment variables
 
-Some command arguments can be specified via environment variables:
+`WH_LOG_LEVEL`: Sets log level (silent, trace, debug, info, warn, error, fatal.) Defaults to info.
 
-        --token         WH_TOKEN
-        --api-key       WH_API_KEY
-        --target        WH_TARGET
-        --command       WH_COMMAND
-
-General 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
 
@@ -57,41 +50,55 @@ Lists commands available to the CLI.
 
 ### `forward`: Forward requests
 
-The `forward` command listens for new incoming requests sent to your Webhook.site URL and immediately relays them to any URL you specify, or simply `localhost` (so it can be used as an ngrok alternative). This URL can be any URL that the machine running Webhook.site CLI can access.
+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.
 
-* The token ID (`--token`) parameter must specify the Webhook.site URL ID (also called token ID). The token ID is the long 36-character ID at the end of your Webhook.site URL.
-* An API key (`--api-key`) must also be specified when the token belongs to a Webhook.site account, and can be generated from the Webhook.site [Control Panel](https://webhook.site/control-panel).
-* Finally, the target (`--target`) specifies where traffic should be redirected (defaults to `https://localhost`)
+| Parameter            | Environment Variable | Description                                                                                                                                                       |
+|----------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--token=`           | `WH_TOKEN`           | Required. The Webhook.site URL ID (also called [token ID](/api/tokens.html#api-endpointstokens-urls-email-addresses))                                                       |
+| `--api-key=`         | `WH_API_KEY`         | An [API key](/api/about.html#api-key), required when using a Token that belongs to a Webhook.site account                                                                    |
+| `--target=`          | `WH_TARGET`          | Specifies URL where traffic should be forwarded.<br>Default: `https://localhost`                                                                                  |
+| `--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.<br>Set to `0` to disable bidirectional forwarding.<br>Default `5`. Max `10`. |
+| `--keep-url`         |                      | When specified, disables URL merging (see below.)                                                                                                                 |
 
 #### Example
 
 ```shell
 whcli forward \
   --token=1e25c1cb-e4d4-4399-a267-cd2cf1a6c864 \
   --api-key=ef6ef2f8-3e48-4f77-a54c-3891dc11c05c \ 
-  --target=https://example.com
+  --target=https://localhost:8080
 ```
 
-Custom Action variables are replaced in the `--target` argument.
+#### 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`.
+
+#### 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, use the special hostname `host.docker.internal`. [More info here](https://stackoverflow.com/a/67781603).
+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](https://stackoverflow.com/a/67781603).
 
 #### 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 and value:
-
-```bash
-NODE_TLS_REJECT_UNAUTHORIZED="0"
-```
+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"`
 
 ### `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/tokens.html#api-endpointstokens-urls-email-addresses))                                                       |
+| `--api-key=`         | `WH_API_KEY`         | An [API key](/api/about.html#api-key), if using a Token that belongs to a Webhook.site account                                                                    |
+| `--command=`         | `WH_COMMAND`         | Specifies which command should be run                                                                                    |
+
 #### Example
 
 ```shell

diff --git a/docs/news.markdown b/docs/news.markdown
@@ -22,6 +22,11 @@ Subscribe below to receive updates about improvements and new features on Webhoo
 </form>
 </div>
 
+## 15 July 2024
+
+* As of version 0.2.0, the Webhook CLI `forward` command now works bidirectionally, forwarding the response back to your Webhook.site URL, acting as a proxy. [More info here](/cli.html#bidirectional-forwarding)
+* Webhook.site URLs can now also be used as subdomains. `https://webhook.site/my-url` and `https://my-url.webhook.site` are now equivalent. Custom domains are currently not supported.
+
 ## 9 July 2024
 
 * New Custom Action: HubSpot Create Contact, which lets you easily create new leads in the HubSpot CRM system. [More info here](/custom-actions/action-types.html#hubspot)