From 94a9ec62d6da702a00bf176fccf329adddeeea10 Mon Sep 17 00:00:00 2001 From: Simon Fredsted Date: Mon, 15 Jul 2024 17:02:13 +0200 Subject: [PATCH] Update docs --- docs/api/requests.md | 33 +++++++++++++++++++++++++++++ docs/api/tokens.md | 5 +++-- docs/cli.md | 49 +++++++++++++++++++++++++------------------- docs/news.markdown | 5 +++++ 4 files changed, 69 insertions(+), 23 deletions(-) diff --git a/docs/api/requests.md b/docs/api/requests.md index 63ae56a..a548b31 100644 --- 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 index 641d1cc..e2b3a4f 100644 --- 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 index 048d6e9..0aed821 100644 --- 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,11 +50,15 @@ 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.
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.
Set to `0` to disable bidirectional forwarding.
Default `5`. Max `10`. | +| `--keep-url` | | When specified, disables URL merging (see below.) | #### Example @@ -69,29 +66,39 @@ The `forward` command listens for new incoming requests sent to your Webhook.sit 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 index 77a88ad..93fd6a5 100644 --- a/docs/news.markdown +++ b/docs/news.markdown @@ -22,6 +22,11 @@ Subscribe below to receive updates about improvements and new features on Webhoo +## 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)