Trigger Run via Webhook
Last updated
Last updated
Before you can use webhooks to trigger TaskBot run on your desktop agent, you need to log in to your agent, as described here: Log in to the Agent.
Go to your TaskBot builder page, open TaskBot Settings and click on Generate Webhook.
Once generated, you will be able to copy the link and use it to trigger TaskBot run programmatically. You can use this link in third-party applications such as Zapier, Make, Pabbly, etc. The webhook can be triggered with a POST or GET method.
Beware that anyone with this link can trigger TaskBot run on your account. If you ever shared this link with anyone and now want to remove their access, you can either deactivate your webhook link or generate a new one.
Simply toggle Webhook is active option off. If the webhook is not active, it cannot be triggered.
To generate a new link, delete your current one by clicking on the trash bin icon and then click on Generate Webhook button again. This action will generate a new link, and the old one will be permanently deleted.
In a POST request, you can send dynamic data via variables. Agent of version 1.1.51 also supports query parameters (in both GET and POST requests).
Your data from the request body is always saved in the variable called zw_webhook_data. You do not need to create this variable manually. Whenever you trigger your TaskBot by a webhook, the variable will be updated or, if not created yet, automatically created.
The data is saved in stringified JSON format.
Tip: You can access nested objects or arrays that were saved to zw_webhook_data in Write JavaScript building block by using JSON.parse() method. Here is an example:
You can also create variables, and the data in your webhook payload will be matched to those. In addition to matching, the whole payload will still be saved to the aforementioned zw_webhook_data variable.
Example
Consider your TaskBot has these variables:
You can add variable names and values as key-value pairs to your request body. For example, if you make your request via Postman (or any other API application), this is how it would look like:
After sending the webhook request as shown above, this would be the new state of your variables:
You can create variables as JSON paths to match nested objects or arrays (as well as execute JSON path supported queries on your payload).
Example
Consider this to be your webhook payload data:
This is how you can create a variable for one of the nested values:
JSON path operators (wildcard, filter, recursive descent) and query behavior are supported.
Here is an example. Consider this to be your webhook payload data:
To get an array of all cities, you can use the wildcard operator * as in cities[*].city.
Similarly, you can use filter operators supported by JSON path to query specific data. Examples:
Filter for the city object where city is Berlin: cities[?(@.city==="Berlin")].
Filter for the cities with population over 5M: cities[?(@.population>5000000)]. This will return an array of city objects of those cities where population is over 5M.
You do not need to include all (or any at all) variables in your body request. Include only those variables that you need to match data to.
Matching is case-sensitive. For example, "Link" will be matched to "Link" and will not be matched to "LINK" or "link".
JSON path variable can be created with or without the dollar $ character. You can evaluate your JSON path here: https://jsonpath.com/. The resource can also help you validate your JSON path syntax.
If your JSON path is invalid or there is no match between some of the TaskBot variables and the webhook payload data, no error will be thrown.
Sometimes you might want to trigger another TaskBot within a TaskBot run. For this, you can use Send HTTP Request building block (see APIs: Send HTTP Request). See example set-up below.
