ThingWorx Flow > Creating and Starting a Workflow Using a Webhook
Creating and Starting a Workflow Using a Webhook
A Webhook is a generic trigger that can be used in external systems and is manually customized to call ThingWorx. The Webhook provides a URL that can be invoked by other systems to start the workflow.
Adding a Webhook
Follow these steps to add a Webhook to a workflow.
1. Create a new workflow by providing a suitable name to the workflow.
2. On the start icon, click . A list of all triggers appears.
3. Select Webhook from the list. The Webhook configuration window opens as shown in the figure that follows:
The URL that can be used to execute the workflow, appears in the URL field.
4. Select the Async check box if you want the webhook to execute asynchronously. When executed asynchronously, the call to the Webhook returns immediately and does not wait for the workflow to complete.
5. Click ADD to specify the input parameters that are passed to the workflow when the webhook is called. For each parameter, enter the following information:
a. Name—Name of the input parameter
b. Description—Description
c. Base Type—Type of input
6. Click Done.
For Workflows that are triggered by webhooks, you can define a return parameter from the workflow. The calling system can then get and process the results from the workflow execution.
When he Async check box is not selected, you must define the webhook to run synchronously, for the calling system to get the return parameter.
To define the return parameter, do the following:
1. On the end action, click . The Output window opens.
2. Select the Base Type of the data to be returned.
3. Specify the Data value to return from the fields that appears in the input panel on the right side.
4. Click DONE.
Invoking a Webhook
After defining a webhook on a workflow, use the URL of the webhook to initiate a flow execution. This can be done by using an HTTP request with the standard mechanism to invoke the ThingWorx REST APIs.
Configure the HTTP request as follows:
HTTP Headers
Authorization—Basic <encoded username/password> or
appkey—<your predefined app key here>
application/json—a JSON payload with inputs to the workflow, where the names match the parameter names specified on the workflow.
For example, if the workflow is defined with a Webhook and two input parameters defined as follows:
Name: "param1", Type: "STRING"
Name: "param2", Type: "XML"
Then workflow is configured to return a STRING.
The JSON payload in the Body of the HTTP request is as follows:
Body Payload
{"param1": "This is a string parameter", "param2": "<xml><field1>helloworld</field1></xml>"}
If the Webhook is set to Asynchronous = false, then the request to invoke the Webhook waits until the workflow completes, and the data from the workflow returns in the HTTP response. The response format follows ThingWorx service invocation conventions and is determined by the Accept header in the request. In this case, the response is in JSON as follows:
"dataShape": {
"fieldDefinitions": {
"result": {
"name": "result",
"description": "result",
"baseType": "STRING",
"ordinal": 0,
"aspects": {}
"rows": [
"result": "<workflow result here>"
If the Webhook is set to Asynchronous = true, then the request to invoke the webhook returns immediately and no data from the workflow is returned in the HTTP response.
For testing, workflows that have webhooks can be invoked using a tool like Postman or curl. See an example command for invoking a webhook trigger:
curl --request POST \
--url https://<server>/Thingworx/Things/FlowThing/Services/webhook_flow \
--header 'Accept: application/json' \
--header 'Authorization: Basic <encoded_user_name_password>'
--header 'Content-Type: application/json' \
--header 'cache-control: no-cache' \
--data '{ "param1": "This is a string parameter", "param2": "<xml><field>helloworld</field></xml>"}