Run a flow through a webhook

A Webhook trigger starts a flow when an external system sends an HTTP request to a Mindflow URL. You choose asynchronous or synchronous mode, optionally require an API key, and can return a custom HTTP response with a Webhook response step. Screenshots on this page show the Webhook trigger Settings and Auth tabs so you can match the labels in Studio.

When to use

• An external ticketing system, SIEM, form, or middleware must start a flow over HTTPS.
• You need an immediate HTTP acknowledgment (async) or a response body from the flow (sync).
• Prefer Run a flow from an AI··Room when operators should start the flow from chat.
• Prefer Run a flow through email when the source is inbound email.
• Prefer Call a flow when one Mindflow flow should start another inside Studio.

Before you begin, you need permission to create and deploy flows in the environment. Deploy the flow before callers rely on the webhook URL in production.

Guide

Add a Webhook trigger

A Webhook is the trigger that exposes HTTPS endpoints for the flow. Studio shows copyable URLs after you add the step.

1. Open the flow. Create or open the flow in the designer.

2. Add a step manually. On an empty canvas, choose Add a step manually.

   

3. Choose Webhook. In the step catalog, open Triggers, then choose Webhook.

   

4. Rename and describe the step. Rename the Webhook step and fill a description so the designer shows why this trigger exists.

5. Open Settings. On the Webhook step, open the Settings tab. Copy Asynchronous (TLS) or Synchronous (TLS) from the read-only fields. When mTLS is enabled for your environment, Studio also shows Asynchronous (MTLS) and Synchronous (MTLS).

   

Choose asynchronous or synchronous mode

Asynchronous returns an HTTP response as soon as Mindflow accepts the request, without waiting for the flow to finish. Synchronous waits for the flow (and an optional Webhook response step) before returning.

Copy the matching URL from Settings. Studio shows the query-param route (…/run-async-qp or …/run-sync-qp) with the trigger id in the path. Hostnames come from your tenant (for example webhook-….mindflow.dev).

Asynchronous (TLS) example

curl "https://webhook-{tenant}.mindflow.dev/playbooks/{trigger-id}/steps/start/run-async-qp"

Synchronous (TLS) example

curl "https://webhook-{tenant}.mindflow.dev/playbooks/{trigger-id}/steps/start/run-sync-qp"

Note

mTLS uses a separate hostname when your environment has mutual TLS enabled. If Security protocol or the mTLS URL fields are missing, contact Mindflow support.

Secure the webhook with an API key

Without an API key, any caller who knows the URL can start the flow. On the canvas, the Webhook step shows security status badges (for example an open lock when there is no API key protection). On Auth, generate a key so callers must send it—the open-lock badge clears once a key is configured.

1. Open Auth. On the Webhook step, open the Auth tab.

   

2. Generate API key. Choose Generate API key. Copy the key and store it with your caller. Use Rotate or Delete from the key menu when you need to replace or remove it.

   

Send the API key and flow deployment id

Callers must identify the flow and, when a key exists, authenticate. Prefer headers over query parameters when your caller supports them.

API key in header

Send the key as x-api-key. Use a non--qp path URL when the trigger id is already in the path:

API key header

curl "https://webhook-{tenant}.mindflow.dev/playbooks/{trigger-id}/steps/start/run-async" \
  -H "x-api-key: YOUR_API_KEY"

API key in query

Append apikey on the query-param route. Prefer headers when you can; query keys can appear in proxy logs.

API key query parameter

curl "https://webhook-{tenant}.mindflow.dev/playbooks/{trigger-id}/steps/start/run-async-qp?apikey=YOUR_API_KEY"

Note

Query-parameter auth remains supported for callers that cannot set headers (for example some Atlassian Jira webhook configurations).

Id in path

The Settings copy fields already include the trigger id in /playbooks/{trigger-id}/…. That is the usual path for the URLs Studio shows.

Trigger id in path

curl "https://webhook-{tenant}.mindflow.dev/playbooks/{trigger-id}/steps/start/run-async" \
  -H "x-api-key: YOUR_API_KEY"

Id in header

Use the header-only URL and send the flow deployment id as x-mindflow-flow-deployment-id (or the legacy alias x-mindflow-playbook-id):

Flow deployment id header

curl "https://webhook-{tenant}.mindflow.dev/playbooks/steps/start/run-async" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-mindflow-flow-deployment-id: {flow-deployment-id}"

Caution

Studio’s Webhook headers callout may show x-flow-deployment-id. Callers must use x-mindflow-flow-deployment-id or x-mindflow-playbook-id — those are the headers the webhook runtime accepts.

Return a custom HTTP response

Webhook response sets the status code, headers, and body for a synchronous webhook call. Place it where the flow should reply. The flow can continue after the response; later steps keep running asynchronously.

1. Add Webhook response. Open Add a step, choose Flow, then Webhook response.

   

2. Configure the response. On Input, set Status Code, optional Headers, and Body (JSON, Text, or XML). Use data pills for dynamic values.

   

3. Call the synchronous URL. Use Synchronous (TLS) (or mTLS) from Webhook Settings — not the asynchronous URL.

   

Note

The flow must reach Webhook response within 25 seconds. Otherwise Mindflow cannot return your custom response and the synchronous call fails. On non-webhook triggers, Webhook response is ignored and the run continues.

Limit callers by IP

On the Webhook step, open Advanced and add Allowed IPs when only specific networks should call this endpoint. Organization-level allowlists apply as well — see Restrict webhook callers with an IP allowlist.

Example

A SOC platform posts a new alert JSON to Mindflow. The flow Ingest SIEM alert starts with a Webhook named Receive SIEM alert, uses an API key in x-api-key, and runs asynchronously so the SIEM gets an immediate acknowledgment while enrichment continues in later steps.

For a caller that needs a custom body back (for example a chatbot middleware), use the synchronous URL and a Webhook response step that returns status 200 and a short text or JSON body within 25 seconds.

Authorizer flow pattern

When a vendor sends a token you must verify before the real automation runs, put validation on a front webhook flow, then call the destination flow only after the check passes.

1. Receive the vendor request. Start with a Webhook (often synchronous).

   

2. Validate the token. Call the vendor API (for example a Google OAuth token check).

   

3. Continue or reject. On success, start the destination flow (for example with Call a flow). On failure, return an error with Webhook response.

   

Keep in mind

• Deploy the flow before external systems depend on the webhook URL.
• Supported HTTP methods include GET, POST, and PUT.
• Prefer x-api-key and x-mindflow-flow-deployment-id headers over query parameters when the caller can set headers.
• For network-level control, combine webhook Allowed IPs with the organization allowlist — see Restrict webhook callers with an IP allowlist.

Related

Trigger your flow · Restrict webhook callers with an IP allowlist · Run a flow from an AI··Room · Manage version and deployments