Sync/async execution of a specific workflow with an integration trigger

Webhooks are used in Torq to trigger workflows with events from third-party vendors. When you create a trigger integration (of a specific third-party vendor or a generic webhook), you get a webhook URL (endpoint) that you can provide to any third-party vendor to get events from them. The integration can be set as a trigger for any number of workflows.

You can select an extended version of an integration webhook URL (endpoint) to trigger a specific workflow. You can also select whether to execute it synchronously or asynchronously. For synchronous executions, you can use output parameters to modify the response status, body, and headers according to your needs.

When to use

• Synchronous executions enable external systems to trigger a specific workflow and get a fully customizable response based on the workflow logic and output: define the status, body, and headers of the response returned by Torq according to the third-party requirements.
• Asynchronous executions can be used to test a new or modified workflow. Trigger only the workflow you want to test with a predetermined trigger event and check that the execution output matches the expected output.

Select a trigger type

1. Open the workflow you would like to trigger.
2. Select the workflow trigger. Click on Webhook URL to get all the trigger types.
3. Select a trigger type:
   • Webhook URL: trigger all workflows that are using this trigger integration.
   • Asynchronous URL: trigger only this specific workflow. The response to the execution request will include the workflow execution ID, which can be used to periodically check whether the execution is complete and the execution output is available. The URL structure is: <integration webhook>/workflows/<workflow ID>. For example: https://hooks.torq.io/v1/webhooks/af6aab8d-****-****-****-74259a93b18f/workflows/710c5349-b617-****-****-e15671ca4ffb
   • Synchronous URL: trigger only this specific workflow. The response to the execution request will be returned when the execution is complete, and it will include the execution output. The HTTP response is customizable. The URL structure is: <asynchronous URL>/sync
     
4. Click the copy icon to copy the selected URL.

Execute the workflow

Provide the URL you copied (synchronous or asynchronous) to a third-party vendor to trigger the specific workflow when receiving an event. Alternatively, you can use the URL to trigger the workflow manually, simulating the automatic trigger.

Below is an example of the cURL syntax to trigger the workflow.

curl <Synchronous URL or Asynchronous URL> -H "auth_header_name:secret" -d '{"body": [1,2,3]}'

The trigger event for this example is:

{
  "body": [
    1,
    2,
    3
  ]
}

Get the execution output

Getting the output differs according to whether the workflow execution is synchronous or asynchronous.

Synchronous execution

The response to the execution request from the previous section will contain the execution output and will be returned as soon as it's available. If the execution takes more than 50 seconds to complete, the Execution is in progress response and the execution ID will be returned after 50 seconds. Use the execution ID to retrieve the execution status as you would for asynchronous execution. Note that you can use output parameters to modify the HTTP response according to your needs.

Asynchronous execution

1. The response to the execution request from the previous section will contain the execution ID: {"execution_id":"c9a0769f-b8a3-****-****-b57c138b5523","status":"ok"}
2. Use the Torq public API retrieve an execution call to continuously check the execution status until the execution is complete and the output is available.

curl --request GET \
  --url https://api.torq.io/public/v1alpha/executions/<execution_id> \
  --header 'Authorization: Bearer <bearer_token>' \
  --header 'accept: application/json'

Synchronous execution: use output parameters to determine the HTTP response

By default, the workflow execution output will contain the output parameters and values or JSON object defined in the Exit operator.

There are three parameter names you can use to modify the HTTP response:

Below is an example of how these parameters can be added to an Exit operator.

The parameter values determine the HTTP response.

Content types

To have the HTTP response interpreted in a format other than the default application/json, you can override the Content-Type header and specify the desired format. Refer to the example above.

These are the supported content types:

• application/json - the default format
• text/csv
• text/plain
• text/html
• text/xml
• Other - for additional content types, contact Torq support.

Example use case: handling CORS requests with synchronous executions

Cross-Origin Resource Sharing (CORS) is an HTTP header mechanism allowing a server to specify origins other than its own from which a browser can load resources. It involves an initial request to the server to confirm permission for the actual request, with the browser sending headers indicating the intended HTTP method and headers for the request.

1. Use a webhook integration that can accept raw HTTP requests as the workflow trigger.
2. In order to handle OPTIONS requests differently than HTTP requests, add a condition checking the HTTP method: {{ $.event.http_method }}
3. Use two Exit operators to adjust the response according to the HTTP method.

Sync/async execution of a shared workflow

For a workflow that's shared with your workspace, you won't have the option to copy the Webhook URL as explained above. Instead, you'll need to obtain the Webhook URL from the workflow source workspace, or you can ask an Owner from that workspace to send it to you. Be sure to update the workflow ID to match the one in your workspace.

Troubleshooting

Below are the responses you can get when executing the workflow with the extended webhook or when trying to retrieve the execution.