Webhooks
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 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.
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.
You can only see the token once, when it's created. Make sure to store it securely!
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>
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.