Triggering workflows (HTTPS & CLI)

There are two ways to start a workflow run from outside the dashboard UI:

The wisebot CLI also supports dashboard APIs (status, agents, logs, playground, and more) with different environment variables—see Wisebot CLI and HTTP API.

External systems start workflows by POSTing JSON to the workflow trigger URL from the editor. You can do that with:

There is no separate workflow-only SDK package. Webhook triggers are HTTPS + JSON (or wisebot workflow trigger). For TypeScript, use client.workflows.run() on the TypeScript SDK for the dashboard API path.

Input steps read JSON keys from the POST body; use the same field names you configured on each Input step (they appear in Run now and in the editor).

Run now in the dashboard fills the same input bag as manual runs. Webhooks merge flat JSON keys into that bag. The dashboard API wraps values under inputs: { "inputs": { "fieldName": "value" } }.

Dashboard API (POST /api/v1/flow/{workflowId})

Run a workflow synchronously with your web app credentials (not the webhook secret).

POST https://<app>/api/v1/flow/<WORKFLOW_ID>
Authorization: Bearer <JWT or wb_live_…>
Content-Type: application/json

{ "inputs": { "ticketId": "T-1", "message": "Hello" } }

• Auth: Dashboard JWT or organization API key (wb_live_…).
• Body: Optional { "inputs": { … } } — keys must match Input step field names.
• Response: { "ok", "runId", "result", "error" }.
• IP rules: Honors the workflow’s allow/block lists (same as public form links).

TypeScript SDK:

await client.workflows.run("<workflowId>", { inputs: { ticketId: "T-1" } });

Python (requests):

r = requests.post(
    f"{BASE}/api/v1/flow/{workflow_id}",
    headers={**H, "Content-Type": "application/json"},
    json={"inputs": {"ticketId": "T-1"}},
    timeout=300,
)
r.raise_for_status()
print(r.json())

Webhook contract

When the workflow editor shows a trigger URL, requests look like this:

POST https://<host>/workflows/trigger?workflowId=<WORKFLOW_ID>
Authorization: Bearer <WEBHOOK_SECRET>
Content-Type: application/json

{ "message": "Hello", "threadId": "…" }

• workflowId — Identifies the workflow (from the editor URL or your administrator).
• Secret — Create it under Run automatically → Webhook; send it as Authorization: Bearer … or X-Workflow-Secret.
• Body — Optional JSON object; keys merge into the same inputs as Run now (for Input nodes).

Responses are JSON (ok, runId, result, or error). Enable the webhook and create a secret first.

curl

export WISEBOT_WORKFLOW_TRIGGER="https://<host>"
export WF_ID="your_workflow_id"
export WF_SECRET="your_webhook_secret"

curl -sS -X POST "$WISEBOT_WORKFLOW_TRIGGER/workflows/trigger?workflowId=$WF_ID" \
  -H "Authorization: Bearer $WF_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message":"From curl"}'

Copy <host> from the workflow screen when it is available.

Wisebot workflow trigger

Install and global options for @wisebotai/cli are documented in Wisebot CLI and HTTP API. For workflow runs you only need the workflow environment variables (below), not WISEBOTAI_BASE_URL.

Environment

Command

export WISEBOT_WORKFLOW_TRIGGER_ORIGIN="https://<host>"
export WISEBOT_WORKFLOW_SECRET="…"

wisebot workflow trigger "<workflowId>" --data '{"message":"from CLI"}'

Omit --data for an empty body. The CLI prints the JSON response (pretty-printed when valid JSON).

SDK: call from your application

Use your HTTP client to POST UTF-8 JSON to the trigger URL with the Bearer secret (or X-Workflow-Secret). Retry and idempotency are your responsibility if the caller retries on timeout.

TypeScript / Node (fetch)

const origin = process.env.WISEBOT_WORKFLOW_TRIGGER_ORIGIN!; // https://<host>
const secret = process.env.WISEBOT_WORKFLOW_SECRET!;
const workflowId = process.env.WISEBOT_WORKFLOW_ID!;

const base = origin.replace(/\/$/, "");
const url = `${base}/workflows/trigger?workflowId=${encodeURIComponent(workflowId)}`;

const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${secret}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "from Node" }),
});

const text = await res.text();
if (!res.ok) throw new Error(text || res.statusText);
const data = JSON.parse(text) as Record<string, unknown>;

Python (requests)

import os
import requests

origin = os.environ["WISEBOT_WORKFLOW_TRIGGER_ORIGIN"].rstrip("/")
secret = os.environ["WISEBOT_WORKFLOW_SECRET"]
workflow_id = os.environ["WISEBOT_WORKFLOW_ID"]

url = f"{origin}/workflows/trigger"
params = {"workflowId": workflow_id}
headers = {
    "Authorization": f"Bearer {secret}",
    "Content-Type": "application/json",
}
body = {"message": "from Python"}

r = requests.post(url, params=params, headers=headers, json=body, timeout=60)
r.raise_for_status()
print(r.json())

Other languages

Use the same URL, query parameter, headers, and JSON body as in the Webhook contract section—Go, Java, Ruby, C#, etc.

Choosing an approach

Related

• Python integration (HTTP) — requests / httpx for dashboard **GET**s and workflow POST
• TypeScript SDK (@wisebotai/sdk) — client.workflows.run() plus agents, chat, playground
• Wisebot CLI and HTTP API — Full wisebot command reference and /api/v1/… HTTP usage
• Workflows overview — Building steps, triggers, and schedules
• Example workflows — Ready-made patterns (summaries, webhooks, schedules, MCP, code)
• MCP overview — Integrations you can use inside a workflow with MCP tool steps