Skip to main content

Webhooks

tip

Snippet of a Deno/TypeScript script using only native JavaScript to trigger a webhook can be found on Windmill Hub.

Getting started​

Webhooks are a way to interact with Windmill using standard web technologies. Each Script and Flow created in the app gets two types of autogenerated webhooks, depending on how they are triggered, and what their return values are. In all cases, webhooks are endpoints accepting only POST requests with arguments as body.

Addresses​

Webhook endpoints

Webhook links can be found on the "Detail" page of the Scripts and Flows. For more information about Scripts or Flows, refer to the Getting Started section.

Each webhook has two URLs, one with the path to the script, i.e. /p/u/<your_user>/<your_script_name>, which will always trigger the latest version of the Script/Flow and the other one with just a hash, i.e. /h/<hash>, hiding potentially sensitive information and always corresponding to that version of the script, even with overwrites.

Asynchronous​

Jobs can be triggered in asynchronous mode, meaning that the webhook is triggered, and the returning value is the uuid of the job that was assigned the execution of the underlying code.

These links are available in the "UUID/Async" tab.

Synchronous​

The second type of autogenerated endpoint is the synchronous webhook. This webhook triggers the execution, automatically extracts the underlying code's return value and returns it as the response.

These links are available in the "Result/Sync" tab.

caution

Be cautious with potentially long-running jobs in synchronous mode.

API token​

To interact with Windmill you always need to use Bearer token authentication.

You can generate tokens for your own account in the User Settings menu on the app. Open it by clicking your username on the side menu, then select "Account settings".

Labels are only used to allow users to easily distinguish keys.

caution

You can only see the token once, when it's created. Make sure to store it securely!

Create new tokens

Triggering​

Once you have a webhook URL and a user token, issue a POST request to the endpoint and you will get the appropriate return as response.

The bearer token must be passed as either an Authorization: Bearer <TOKEN> header, or as a token query parameter: https://<instance>/<route>?token=<TOKEN>

caution

Because of security reasons it is highly recommended to pass token in the header. If it's not possible, then URL that contains the token should be treated as a secret (for more context please check OWASP ref.1 and OWASP ref.2).

Examples using cURL:

# Header
curl -X POST \
    --data '{}'                            \
    -H "Content-Type: application/json"    \
    -H "Authorization: Bearer supersecret" \
    ".../w/demo/jobs/run_wait_result/p/u/bot/hello_world_deno"
# Query parameter
curl -X POST                               \
    --data '{}'                            \
    -H "Content-Type: application/json"    \
    ".../w/demo/jobs/run_wait_result/p/u/bot/hello_world_deno?token=supersecret"

You can find an example using only standard Deno libraries on the Windmill Hub.

You can also verify that the job has been triggered and ran (or investigate any encountered issues), by checking the Runs page on the app.

Runs page