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.

Authentication

All webhook requests require HMAC-SHA256 signature verification. The signature must be included in the X-Webhook-Signature header.

The HMAC secret is configured per workflow in the Trigger node settings within the workflow editor.

Computing the Signature

The signature is the HMAC-SHA256 hex digest of the raw request body using your configured secret:

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

Requests with missing or invalid signatures are rejected with a 401 status code.

Request Format

• Method: POST
• Content-Type: application/json
• Body: JSON payload that 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=$(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-Webhook-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

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".