Overview
Trigger workflows from external services
In Torq, webhooks let external services trigger workflows by sending events to a generated URL. You can use either a vendor trigger integration or a generic webhook integration to receive incoming events.
For every trigger integration, Torq provides three trigger URL options:
Webhook URL: Triggers all workflows using the selected trigger integration.
Asynchronous URL: Triggers one specific workflow asynchronously.
Synchronous URL: Triggers one specific workflow synchronously and returns the workflow response when execution completes.
These options are available for all trigger integrations, including vendor integrations and generic webhooks.
Choose the right execution type
Use synchronous executions to allow external systems to trigger a specific workflow and receive a fully customizable response based on the workflow logic. You can define the response status, body, and headers to meet third-party requirements.
Use asynchronous executions to trigger a specific workflow without waiting for completion. This is useful for testing new or updated workflows by sending a predefined event and validating that the execution output matches the expected result.
How to use
Select a trigger execution type
Open workflow: Open the workflow you want to trigger.
Select trigger: Click the workflow trigger.
Open trigger URLs: Click Webhook URL to view all available trigger types (see figure above).
Select trigger type: Choose one of the following:
Webhook URL: Trigger all workflows using this trigger integration.
Asynchronous URL: Trigger only this workflow and return an execution ID.
Synchronous URL: Trigger only this workflow synchronously and return the execution output.
Copy URL: Click the copy icon to copy the selected URL.
Trigger URL types
Webhook URL: Use this URL to trigger all workflows that use the selected trigger integration.
Asynchronous URL: Use this URL to trigger only the selected workflow. The response includes the workflow execution ID, which you can use to check execution status and retrieve output later.
Synchronous URL: Use this URL to trigger only the selected workflow synchronously. The response is returned when the workflow execution completes. You can customize the HTTP response using output parameters.
Trigger a workflow
Send request: Provide the copied synchronous or asynchronous URL to a third-party service, or use it manually to simulate an incoming event.
Example cURL request:
curl <Synchronous URL or Asynchronous URL> -H "auth_header_name:secret" -d '{"body": [1,2,3]}'Authentication headers are supported and recommended to prevent unauthorized access.
The workflow runs in production using the latest published version. If the workflow is not published, it will not execute.
Get execution output
The returned output depends on the execution type.
Synchronous execution
The response returns the workflow execution output as soon as it is available.
If execution completes within 50 seconds, the response includes the output.
If execution takes longer than 50 seconds, Torq returns:
201: Execution is in progress.The execution ID.
If the workflow execution fails, Torq returns a 200 (OK) status with an error message in the response body (for example: {"execution-id":"<id>","message":"Workflow execution failed due to error"}).
You can then use the execution ID to retrieve the result as you would for an asynchronous execution.
Asynchronous execution
The initial response includes the execution ID:
{"execution_id":"c9a0769f-b8a3-****-****-b57c138b5523","status":"ok"}Use the Torq public API to retrieve the execution status and output:
curl --request GET \
--url https://api.torq.io/public/v1alpha/executions/<execution_id> \
--header 'Authorization: Bearer <bearer_token>' \
--header 'accept: application/json'
Customize synchronous HTTP responses
By default, the workflow response includes the output parameters or JSON object defined in the Exit operator. For synchronous executions, you can override the HTTP response using these output parameter names:
body: Returned as the response body. If this parameter exists, other output parameters are not included in the body.
status: Returned as the HTTP status code. Must be a valid HTTP status code.
headers: Added to the HTTP response headers. Must be a JSON object with valid key-value pairs.
These parameters affect only synchronous executions. The following example shows how to add these parameters to an Exit operator.
The parameter values determine the HTTP response.
Set response content type
The default response content type is application/json. To return a different format, override the Content-Type header in the response headers. Supported content types include:
application/jsontext/csvtext/plaintext/htmltext/xml
For additional content types, contact Torq Support.
Use case: Handling CORS requests with sync executions
Cross-Origin Resource Sharing (CORS) is an HTTP mechanism that allows a server to specify which external origins are permitted to access its resources. It involves a preliminary request in which the browser sends headers indicating the intended method and headers, allowing the server to approve or deny the request before it is executed. You can use synchronous webhook executions to respond to CORS requests.
Use raw HTTP webhook: Configure a webhook integration that can accept raw HTTP requests.
Check HTTP method: Add a condition using
{{ $.event.http_method }}to distinguishOPTIONSrequests from standard HTTP requests.Return different responses: Use separate Exit operators to return the appropriate response for each method.
This allows Torq to respond correctly to browser preflight and cross-origin requests.
Use sync or async execution with shared workflows
For workflows shared with your workspace, you cannot copy the webhook URL directly from the destination workspace.
To trigger a shared workflow:
Get the webhook URL from the source workspace.
Ask an Owner in the source workspace to provide it.
Update the workflow ID so it matches the shared workflow ID in your workspace.
Troubleshooting
You may receive the following responses when triggering a workflow or retrieving an execution:
200: Success
201: Execution is in progress
400: Invalid integration ID
400: Invalid workflow ID
400: Invalid header
401: Invalid HMAC signature
404: Execution not found
404: Integration not found
404: Workflow not found
413: Payload is too large
429: Rate limit exceeded (limit is 25 executions per second)
500: Internal error; retry the request