Webhooks

A workflow with a Webhook trigger can be started by any system that can send an HTTP request.

Endpoint

POST https://app.flowtrux.com/api/webhooks/<workflowId>

The Trigger node's inspector shows the exact URL with a copy button. The workflow must be active and its Trigger node must be of type Webhook.

Authentication

Every request must authenticate with the workflow's webhook secret. Generate it in the Trigger inspector (Authentication → Generate secret); it is shown once, so copy it immediately. Rotate secret replaces it, and the old secret stops working at once. Without a secret, every call is rejected.

Pick the mode in the Authentication dropdown:

HMAC signature (recommended)

The caller signs the raw request body with HMAC-SHA256 using the secret and sends the hex digest, prefixed with sha256=, in the X-FlowTruss-Signature header. (Senders that use X-Hub-Signature-256 or X-Webhook-Signature with the same format are accepted too.)

BODY='{"event":"order_created","order_id":"12345"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl -X POST https://app.flowtrux.com/api/webhooks/<workflowId> \
  -H "Content-Type: application/json" \
  -H "X-FlowTruss-Signature: sha256=$SIG" \
  -d "$BODY"

Sign exactly the bytes you send - re-serializing the JSON after signing changes the signature.

Access token

For senders that can't compute a signature, send the secret itself:

curl -X POST https://app.flowtrux.com/api/webhooks/<workflowId> \
  -H "Content-Type: application/json" \
  -H "X-FlowTruss-Token: $SECRET" \
  -d '{"key": "value"}'

If the sender can only be given a URL, append ?auth_token=<secret> instead. The token is never included in the workflow's trigger data.

Request format

• Method: POST
• Content-Type: application/json or application/x-www-form-urlencoded. Any other content type arrives as { "body": "<raw text>" }.
• Body: available in the workflow as {{trigger.data}} - e.g. {{trigger.data.order_id}}.
• Query parameters: available as {{trigger._query.<name>}}. A request to …/api/webhooks/<id>?source=crm&priority=high makes {{trigger._query.source}} resolve to "crm".
• Request metadata: {{trigger._webhook}} holds the time, method and headers (credentials removed).

Response modes

Configured in the Trigger node under Webhook Response.

Minimal (default)

Answers at once, before the workflow finishes:

{ "success": true, "executionId": "cm…" }

Last Node Output

Waits for the run and returns the output of the last node that succeeded:

{
  "success": true,
  "executionId": "cm…",
  "data": { "...": "the node's output" },
  "_meta": { "sourceNodeId": "agent-1", "sourceNodeName": "Classify" }
}

Specific Node Output

Waits for the run and returns the output of the node you choose in the inspector, as data.

All Nodes Output

Waits for the run and returns every executed node:

{
  "success": true,
  "executionId": "cm…",
  "data": {
    "http-1": { "name": "Fetch order", "output": { "...": "..." } },
    "agent-1": { "name": "Classify", "output": { "...": "..." } }
  }
}

In the waiting modes, a failed run answers with success: false and an error message, with status 500 unless you set your own status code. If the workflow pauses (a Wait for Callback node), the answer is 202 with "suspended": true and the execution id.

You can set a custom HTTP status code for the answer in the Trigger node.

Errors

Errors come as JSON: { "error": "<message>" }.

Checking webhook info

A GET to the same URL, made while signed in to FlowTrux with access to the workflow, returns its name, whether it is active, whether a secret is configured, the authentication mode and the header the caller must use. Handy when you set up an integration.

Related

• Triggers - all trigger types
• Long Delays & Callbacks - callback URLs that resume a paused run