Use webhooks with workflows

Published

May 6, 2026

Use webhooks to let external systems start ValidMind workflows or trigger paused workflows to continue.

Prerequisites

You are logged in to ValidMind.
You are a Customer Admin or assigned another role with sufficient permissions to configure workflows.¹
You understand how to configure workflows and add steps to workflows.²
You have admin access to the external system that will send webhook requests.

¹ Manage permissions

² Introduction to workflows

Start a workflow via webhook

Start a ValidMind workflow from an external system by sending a POST request to trigger a new workflow.

Add a new workflow, selecting the Via Webhook workflow start option.³
From the Workflow Steps modal, drag and drop a Webhook step⁴ onto the canvas, then connect it to your workflow.
Double-click the step to open the Webhook Step Trigger modal.
Copy or select the webhook details:
- URL — Click Copy for the unique POST webhook URL to use when configuring your external system.
- select target model for payload — Select the model that is associated with the webhook payload from the dropdown.
- Payload — Click Copy for the JSON payload that external systems must send in their POST request, where the value for target_cuid is shown after you select a target:
```
{
  "action": "run_workflow",
  "target": "<target_cuid>",
  "entity_name": "InventoryModel"
}
```
- For the required authentication headers, click Copy for each of the following key-value pairs and paste them into your external system:
  - x-api-key: {API Key}
  - x-api-secret: {API Secret}
- wait for webhook trigger when reached — When enabled, the workflow pauses execution when it reaches this step and waits for the external system to send the POST request.
Click Save.

³ Add new workflows

⁴ Workflow step types

Send a POST request to the webhook URL with a JSON payload that includes the run_workflow action for the target model CUID:

curl -X POST https://api.prod.vm.validmind.ai/vm/api/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxx/xxxx -H 'Content-Type`: `application/json' -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -H 'x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' --data '{
  "action": "run_workflow",
  "target": "<target_cuid>",
  "entity_name": "InventoryModel"
}'

Trigger a paused workflow to continue

Trigger a waiting ValidMind workflow step to continue from an external system. Use this pattern when a workflow pauses at a webhook step and waits for external input before proceeding.

Open the workflow you want to configure, or add a new workflow.⁵
From the Workflow Steps modal, drag and drop a Webhook step⁶ onto the canvas, then connect the step to your workflow.
Double-click the step to open the Webhook Step Trigger modal.
Copy or select the webhook details:
- URL — Click Copy for the unique POST webhook URL to use when configuring your external system.
- select target model for payload — Select the model that is associated with the webhook payload from the dropdown.
- Payload — Click Copy for the JSON payload that external systems must send in their POST request, where the value for target_cuid is shown after you select a target:
```
{
  "action": "run_step",
  "target": "<target_cuid>",
  "entity_name": "InventoryModel"
}
```
- For the required authentication headers, click Copy for each of the following key-value pairs and paste them into your external system:
  - x-api-key: {API Key}
  - x-api-secret: {API Secret}
Click Update Step to save your configuration.

⁵ Add new workflows

⁶ Workflow step types

When the workflow reaches this step, it pauses and waits for the external system.

Send a POST request to the webhook URL with a JSON payload containing the run_step action for the model CUID:

curl -X POST https://api.prod.vm.validmind.ai/vm/api/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxx/xxxx  -H 'Content-Type`: `application/json' -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -H 'x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' --data '{
  "action": "run_step",
  "target": "<target_cuid>",
  "entity_name": "InventoryModel"
}'