Webhook Trigger

Starts workflow execution when an external system sends an HTTP POST request.

Overview

The Webhook Trigger node lets external systems push data into your workflows via HTTP. Each webhook trigger node has a unique URL based on its workflow ID and node ID — no separate secret key is needed.

Use it to:

• Receive data from third-party services (e.g., payment processors, form submissions, CRMs)
• Build event-driven workflows that respond to external events in real time
• Accept file uploads from external systems
• Create custom API endpoints for your workflows

How It Works

1. Add a Webhook Trigger node to your workflow — a unique endpoint URL is generated automatically
2. External systems send HTTP POST requests to your webhook URL
3. The request body becomes the trigger item, passed to downstream nodes

Webhook URL

The webhook endpoint uses the workflow and node IDs:

POST /api/workflows/webhook/{workflowId}/{nodeId}

• workflowId — the workflow's unique ID
• nodeId — the webhook trigger node's unique ID

No secret key or query parameters are required. The full URL is shown in the node header — copy it from there.

Parameters

Parameter	Description	Required
File Upload Mode	How to handle file uploads: None or Multipart form data	No (default: None)

File Upload Mode

Controls how the webhook handles incoming file data:

None (default)

The request body is passed through as-is as the trigger item. Use this for standard JSON payloads.

Multipart form data

Accepts standard multipart file uploads. Configure:

• File Field Name — the form field name for the file (default: file)
• Allow Multiple Files — whether to accept multiple files in a single request

Uploaded files are stored in a temporary bucket and passed as WorkflowFileData items to downstream nodes (e.g., Data Extractor, Copy File).

Production Mode

When the workflow is active, POST requests to the webhook URL:

1. Look up the workflow containing the node
2. Enqueue the workflow execution as a background job
3. Return 202 Accepted with a jobId

{ "jobId": "hj4:abc123-..." }

Polling for Results

Use the result endpoint to poll for job status and data returned by a Workflow Result node:

GET /api/workflows/webhook/result/{jobId}

Response:

{
  "status": "completed",
  "result": {
    "responseData": [
      { "name": "John Doe", "score": 95 }
    ]
  }
}

Status	Description
active / waiting	Workflow is still executing
completed	Workflow finished; result contains the workflow result data
failed	Workflow encountered an error; error contains the message

Test Mode

When developing your workflow, use the test endpoint to send data without activating the workflow:

POST /api/workflows/webhook-test/{workflowId}/{nodeId}

Returns a jobId for polling:

{ "jobId": "550e8400-e29b-..." }

The test data is stored temporarily (60 seconds). In the workflow editor, click Listen for Test Webhook to automatically poll for incoming test data and trigger the workflow when it arrives.

The test endpoint does not require the workflow to be active.

Test Mode Polling

Test mode runs the workflow in the editor and does not store results server-side. Use the workflow editor's output panel to inspect results.

Output

The webhook body is passed directly as the trigger output. For a JSON POST:

{
  "name": "John Doe",
  "email": "john@example.com",
  "event": "signup"
}

For file uploads (when File Upload Mode is Multipart):

{
  "type": "fileData",
  "name": "invoice.pdf",
  "fileInfo": {
    "type": "temporaryLidoBucket",
    "bucketFileName": "abc123.pdf"
  }
}

Examples

Receive Form Submissions

Accept form data and insert into a spreadsheet:

[Webhook Trigger] → [Insert Rows]

curl -X POST \
  "https://your-app.com/api/workflows/webhook/{workflowId}/{nodeId}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane", "email": "jane@example.com"}'

Process and Return Results

Accept data, process it, and return results to the caller:

[Webhook Trigger] → [Edit Item] → [Workflow Result]

# Trigger
curl -X POST "https://your-app.com/api/workflows/webhook/{workflowId}/{triggerNodeId}" \
  -H "Content-Type: application/json" \
  -d '{"input": "data"}'
# Returns: { "jobId": "hj4:abc123" }

# Poll for result
curl "https://your-app.com/api/workflows/webhook/result/hj4:abc123"
# Returns: { "status": "completed", "result": {...} }

Process Uploaded Files

Extract data from uploaded PDFs:

[Webhook Trigger (Multipart)] → [Data Extractor] → [Insert Rows]

With multipart upload:

curl -X POST \
  "https://your-app.com/api/workflows/webhook/{workflowId}/{nodeId}" \
  -F "file=@invoice.pdf" \
  -F 'data={"source": "partner-api"}'

To handle base64-encoded files in JSON payloads, pass the JSON body through as-is and use the File Utils node downstream to convert base64 strings to files.

Payment Webhook

Process Stripe payment events:

[Webhook Trigger] → [If (event = payment_intent.succeeded)] → [Edit Item] → [Insert Rows]

CRM Integration

Sync new contacts from an external CRM:

[Webhook Trigger] → [Edit Item (map fields)] → [Fuzzy Lookup (deduplicate)] → [Insert Rows]

Tips

• The webhook URL is shown in the node header — copy it from there to configure external callers
• Production webhooks return immediately with a jobId — the workflow runs asynchronously in the background
• The workflow must be active for production webhooks to work; test webhooks work regardless
• Use the Listen for Test Webhook button in the editor to automatically detect and run incoming test data
• File uploads are stored temporarily — use Copy File or Google Drive nodes to persist them
• Pair with a Workflow Result node to return data to the caller via the result endpoint
• Job results are retained for 6 hours