Trigger Using Webhook

The Webhook trigger allows you to start a workflow execution when an external service sends an HTTP request to a unique webhook URL. This enables workflows to run automatically based on external events.

Creating a Workflow with Webhook Trigger

1. Navigate to the Workflows Section from the navigation bar on the dashboard.
2. Click on Create new workflow, enter a unique name for your workflow, and click on +Create workflow to create the workflow.
   
3. Configure your workflow. You can refer to the workflow overview documentation to learn how you can configure a workflow.
4. Navigate to the Triggers section and click on Webhooks. By default, the webhook trigger is disabled. Toggle the switch to enable the webhook trigger.
   Once enabled, you can choose the Environment to modify the webhook endpoint URL for that specific environment. For example, if you choose the Production environment, you can Copy URL or Copy as cURL which can then be used to trigger for Production environment accordingly.
   
5. Parameters can be passed to the workflow. The parameter key and their type can be specified in the Parameters field. For example, if you want to pass the name and emp_id parameters to the workflow using the webhook triggers, you can set the Parameters field as follows:

   "name": "string",
   "emp_id": "number"
   
   The Test JSON parameters field can be used to test the webhook trigger. You can enter the parameter values in the Test JSON parameters field and click on the Run button to test the webhook trigger. The workflow will be executed with the parameter values specified in the Test JSON parameters field.

   {
       "name": "John Doe",
       "emp_id": 33
   }
   
6. Find the API endpoint URL in the Endpoint field. You can use this URL to send a POST request to trigger the workflow. You can also click on the Copy button to copy the URL to the clipboard. You can either select Copy URL or Copy as cURL from the dropdown menu. The Copy as cURL option copies the URL as a cURL command which will include details such as the API token and Environment. An example of the Endpoint URL is as follows:

   http://{TOOLJET_HOST}/api/v2/webhooks/workflows/:id/trigger
   
7. The API token is used to authenticate the request. You can find the API token in the API Token field. You can also click on the Copy button to copy the API token to the clipboard.
   info

   Currently, authentication is mandatory for webhooks. Use a bearer token in the Authorization header for authentication.
   Format: Authorization: Bearer <secret_token>
   Example:Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Triggering a Webhook

Let's take a look at an example of triggering a webhook using Postman.

1. Visit Postman, and click New Request.
2. Select the POST Method and paste the Endpoint URL that was copied earlier.
3. Navigate to the Authorization tab, select Bearer Token as the Auth Type, and enter the API token.
4. Go to the Body tab, select Raw, and enter the required parameters in JSON format.
5. Click on Send to trigger the webhook. It will fetch the response from the created workflow.

Async Workflow Query Execution

By default, when a workflow is triggered via the /trigger endpoint, the request waits until the entire execution is complete, which can lead to timeouts if the workflow takes too long.

To avoid this, you can use the /trigger-async endpoint. It starts the workflow in the background and immediately responds with an execution_id and timestamp. You can then track the execution separately.

You'll need to manually append /trigger-async to the endpoint URL. The final URL should look like this:

http://{TOOLJET_HOST}/api/v2/webhooks/workflows/:workflow_id/trigger-async?environment=:environment

Once the execution starts, the webhook response should be in the following format:

{
  "workflow_execution_id": "abc123...",
  "timestamp": "2025-05-15T10:30:45Z"
}

You can track the workflow execution in two ways: by streaming live updates or by polling the execution status at regular intervals.

• Stream live updates:

  http://{TOOLJET_HOST}/api/v2/webhooks/workflows/:workflow_id/execution/:execution_id/stream
• Poll status:

  http://{TOOLJET_HOST}/api/v2/webhooks/workflows/:workflow_id/status/:execution_id

Restrictions on Usage of Webhook Triggers

There are certain restrictions on the usage of webhook triggers that are configurable, both at the instance level and at the workspace level depending on the license. The restrictions are as follows:

• Number of executions per month
• Number of executions per day
• Number of parallel executions
• Execution time per workflow

For limiting parallel executions, the following environment variables can be used:

Environment Variable	Value	Description
WEBHOOK_THROTTLE_TTL	60000	Time in milliseconds for the webhook requests to live
WEBHOOK_THROTTLE_LIMIT	100	Maximum number of requests within the TTL that will be throttled

Whitelisting API endpoints

For Virtual Private Clouds (VPCs), restrict access only to the {TOOLJET_HOST}/api/v2/workflows/* endpoint.