In Torq, webhooks trigger workflows based on events from other services. By setting up a trigger integration for a vendor or a general webhook, you get a URL. Share this URL with other services to receive their events.
You can provide 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.
All three trigger options, Webhook URL, Asynchronous URL, and Synchronous URL, are available for all trigger integrations (vendor integrations and generic).
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
Select a Trigger Type
Open the workflow you would like to trigger.
Select the workflow trigger. Click on Webhook URL to get all the trigger types (see image above).
Select a trigger type:
Webhook URL: trigger all workflows 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
/workflows/. For example:https://hooks.torq.io/v1/webhooks/af6aab8d-****-****-****-74259a93b18f/workflows/710c5349-b617-****-****-e15671ca4ffbSynchronous URL: trigger only this specific workflow synchronously. The response to the execution request, including the execution output, will be returned when the execution is complete. The HTTP response is customizable. The URL structure is:
<asynchronous URL>/sync
Click the copy icon to copy the selected URL.
Execute the Workflow
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 cURL command accounts for authentication headers the webhook may have. We recommend using authentication headers to improve security and prevent unauthorized access to your data.
The workflow will be executed in production using the latest published version. It won't be executed if the workflow doesn't have a published version.
Get the Execution Output
Get the Execution Output
The output differs depending on 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
The response to the execution request from the previous section will contain the execution ID:
{"execution_id":"c9a0769f-b8a3-****-****-b57c138b5523","status":"ok"}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: Customize the HTTP Response
Synchronous Execution: Customize 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:
These parameters will only modify the HTTP response for synchronous executions.
body: The value will be returned as the response body. If this parameter exists, other parameter values will not be included in the execution output. Make sure the parameter type matches the data provided as the value.
status: The value will be returned as the response status code. The status can be specified in either string or number formats. The value must be a valid HTTP status code.
headers: The value will be added to the HTTP response headers. The parameter type must be JSON. The value must consist of valid key-value pairs.
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 Sync 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.
Use a webhook integration that can accept raw HTTP requests as the workflow trigger.
To handle OPTIONS requests differently than HTTP requests, add a condition checking the HTTP method:
##{{ $.event.http_method }}Use two Exit operators to adjust the response according to the HTTP method.
Sync/Async Execution of a Shared Workflow
Sync/Async Execution of a Shared Workflow
For a workflow shared with your workspace, you won't have the option to copy the Webhook URL, as explained above. Instead, you'll need to get 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
Troubleshooting
You can get these responses when executing the workflow with the extended webhook or when trying to retrieve the execution.
200: Success.
201: Execution is in progress. Synchronous execution hasn't been completed yet.
400: Invalid integration ID. The integration ID format is invalid.
400: Invalid workflow ID. The workflow ID format is invalid. If a workflow with the ID exists, ensure the workflow is triggered by the specified integration.
400: Invalid header. Incorrect header name or the header secret doesn't match the header name.
401: Invalid HMAC signature.
404: Execution not found. There is no execution to retrieve. Ensure that no trigger condition prevents workflow execution with the specified event.
404: Integration not found. No integration with the specified integration ID.
404: Workflow not found. No workflow with the specified workflow ID. Make sure the workflow has a published version.
413: Payload is too large. The event body payload is too large.
429: Rate limit exceeded. The workflow execution limit is 25 per second.
500: Internal error. Retry the request.