Webhooks

Webhooks allow external systems to trigger workflow executions by sending HTTP requests to a dedicated endpoint.

Endpoint

POST /api/webhooks/[workflowId]

Replace [workflowId] with the ID of the workflow you want to trigger. The workflow must be active and have a webhook Trigger node.

Authentication

Signing is optional and controlled by the Trigger node: if you set a webhook secret in the Trigger node settings, every request must carry a valid HMAC-SHA256 signature in the X-FlowTruss-Signature header. If no secret is set, requests are accepted without a signature - anyone who knows the URL can trigger the workflow, so setting a secret is recommended for production.

Computing the Signature

The signature is the HMAC-SHA256 hex digest of the raw request body using your configured secret, prefixed with sha256=:

SIGNATURE="sha256=$(echo -n '{"event":"test"}' | openssl dgst -sha256 -hmac "your-secret" | cut -d' ' -f2)"

When a secret is configured, requests with a missing or invalid signature are rejected with a 401 status code.

Request Format

• Method: POST
• Content-Type: application/json (JSON body) or application/x-www-form-urlencoded (form fields). Any other content type is passed through as { "body": "<raw text>" }.
• Body: becomes available as {{trigger.data}} in the workflow.
• Query parameters: available as {{trigger.data._query}} within the workflow.

Response Modes

The response behavior is configured in the Trigger node under the Webhook Response settings.

minimal

Fire-and-forget mode. Returns immediately with the execution ID before the workflow finishes.

{
  "success": true,
  "executionId": "exec-abc123"
}

lastNode

Waits for the workflow to complete and returns the output of the last executed node.

specificNode

Waits for the workflow to complete and returns the output of a specific node, identified by node ID in the Trigger configuration.

allNodes

Waits for the workflow to complete and returns the output of every node in the workflow:

{
  "nodeId1": { "name": "HTTP Request", "output": { ... } },
  "nodeId2": { "name": "Transform", "output": { ... } }
}

Node logs and durations are excluded from the response for security.

Custom Response

You can configure a custom HTTP status code and response headers in the Trigger node webhook settings. These are applied to the webhook response regardless of the selected response mode.

Example

PAYLOAD='{"event":"order_created","order_id":"12345"}'

SIGNATURE="sha256=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "your-webhook-secret" | cut -d' ' -f2)"

curl -X POST https://your-domain.com/api/webhooks/your-workflow-id \
  -H "Content-Type: application/json" \
  -H "X-FlowTruss-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Checking Webhook Info

A GET request to the same URL returns the webhook's public metadata - workflow name, whether it is active, and whether a signature is required (including the expected header name and format). Useful for verifying your integration before sending real events.

Query Parameters

URL query parameters are extracted and made available within the workflow as {{trigger.data._query}}. For example, a request to:

POST /api/webhooks/workflow-id?source=crm&priority=high

Makes {{trigger.data._query.source}} resolve to "crm" and {{trigger.data._query.priority}} resolve to "high".