Webhook Node - VibeFlow

Overview

The Webhook Node is a powerful trigger node that starts workflows via REST API calls. It creates HTTP endpoints that external services, applications, or frontend clients can call to trigger automated workflows with data.

Required Configuration

Basic Settings

Label: Display name for the node
Path: URL path for the webhook endpoint (e.g., “/create-user”, “/sync-data”)
Method: HTTP method: POST, GET, PUT, PATCH, or DELETE

Authentication

Choose how to secure your webhook endpoint:

None

No authentication required
Warning: Anyone with the URL can trigger the workflow

Basic Auth

Username: Required username for basic authentication
Password: Required password for basic authentication
Credentials sent in Authorization header as Base64-encoded username:password

Bearer Token

API Key: Token value (leave empty, users fill in UI)
Environment Variable: Variable name to store the token (e.g., “WEBHOOK_API_KEY”)
Sent as Authorization: Bearer <token>

Header Auth

Header Name: Custom header name (e.g., “X-API-Key”)
Prefix: Optional prefix (e.g., “Bearer”, “Token”)
API Key: Token value (leave empty, users fill in UI)
Environment Variable: Variable name to store the token
Sent as custom header: X-API-Key: <token> or X-API-Key: Bearer <token>

Query Parameter Auth

Query Parameter Name: URL parameter name (e.g., “api_key”)
API Key: Token value (leave empty, users fill in UI)
Environment Variable: Variable name to store the token
Added to URL: ?api_key=<token>

Response Mode

Control when the webhook responds to the caller:

immediately: Return response right away (for async processing)
lastNode: Wait for the entire workflow to finish before responding
onReceived: Acknowledge receipt immediately, process asynchronously

How It Works

Step 1: Create the Trigger

Drag a Webhook Node onto your canvas. This will be the entry point for external API calls to your workflow.

Step 2: Configure the Endpoint

Set the HTTP method (POST for data creation, GET for retrieval, etc.)
Define the webhook path (e.g., “/users/create”)
Choose authentication method to secure the endpoint
Select response mode based on your use case

Step 3: Build Your Workflow

Connect the Webhook Node to backend nodes (Query, Mutation, Agent, etc.) to process the incoming data.

Step 4: Access Webhook Data

Use the $"startNode" reference to access incoming request data in downstream nodes.

Accessing Webhook Data

The webhook is the starting node of your workflow. Use $"startNode" to access different parts of the HTTP request:

1. Request Body (POST/PUT/PATCH)

Access JSON body fields using $"startNode".body.<field> Example: POST request with body { "name": "John", "email": "john@example.com" }

// In a Mutation node field
{
  "field": "name",
  "mode": "From args",
  "value": "$\"startNode\".body.name"
}

2. Query Parameters (All Methods)

Access URL query parameters using $"startNode".queryParams.<param> Example: GET request to /users?status=active&limit=10

// In a Query filter
{
  "field": "status",
  "operator": "==",
  "value": "$\"startNode\".queryParams.status",
  "valueMode": "From args"
}

3. URL Path Parameters

Access URL path variables using $"startNode".params.<param> Example: PATCH request to /users/:userId

// In a Query filter to find the user
{
  "field": "_id",
  "operator": "==",
  "value": "$\"startNode\".params.userId",
  "valueMode": "From args"
}

4. Request Headers

Access HTTP headers using $"startNode".headers.<header> or $"startNode".headers["header-name"] Example: Access custom request ID header

// In a Mutation field
{
  "field": "requestId",
  "mode": "From args",
  "value": "$\"startNode\".headers[\"x-request-id\"]"
}

5. HTTP Method

Access the HTTP method using $"startNode".method Example: Conditional logic based on method

// In an If-Else condition
{
  "field": "$\"startNode\".method",
  "operator": "equals",
  "value": "POST"
}

Common Use Cases

1. Create Resource from External Service

Webhook (POST /users)
→ Mutation (insert using $"startNode".body)
→ Return (respond with created user)

External service sends user data, workflow creates database record and returns result.

2. Query Data via API

Webhook (GET /users?status=active)
→ Query (filter by $"startNode".queryParams.status)
→ Return (respond with user list)

External service queries your data through REST API.

3. Update Resource with Path Parameters

Webhook (PATCH /users/:userId)
→ Query (find user by $"startNode".params.userId)
→ Mutation (patch with $"startNode".body)
→ Return (respond with updated user)

External service updates a specific resource by ID.

4. AI Processing from External Call

Webhook (POST /analyze)
→ Agent (process $"startNode".body.text)
→ Mutation (save analysis)
→ Return (respond with AI results)

External service triggers AI analysis and receives results.

5. Conditional Webhook Processing

Webhook (POST /event)
→ If-Else (check $"startNode".body.action)
  → [true: Create Mutation]
  → [false: Update Mutation]
→ Return

Route webhook requests to different operations based on data.

6. Batch Processing from API

Webhook (POST /batch)
→ For Loop ($"startNode".body.items)
  → Mutation (process each item)
→ Return (respond with results)

Process arrays of data sent via webhook.

7. Proxy to External API

Webhook (POST /sync)
→ HTTP Request (forward $"startNode".body to external API)
→ Return (respond with external API result)

Act as a proxy to transform or route requests to other services.

Important Notes

Webhook is a Start Node

Like Frontend Element and Cron nodes, webhooks are trigger nodes that start workflows. They have no inputs, only outputs.

No Frontend Node Needed

Unlike Frontend Element flows, webhook flows are triggered by external HTTP requests, not user interactions. Do NOT create frontend nodes for webhook-triggered workflows.

Security Best Practices

Always use authentication for production webhooks
Leave “API Key” field empty in configurations; users should provide credentials in the UI
Store sensitive tokens in environment variables
Use HTTPS URLs in production

Response Modes Guide

immediately: Best for async processing where caller doesn’t need to wait
lastNode: Best when caller needs the workflow result
onReceived: Best for long-running workflows where caller just needs acknowledgment

Unique Endpoints

Each webhook path represents a unique REST API endpoint. Use descriptive paths like:

/users/create
/orders/webhook
/sync/data

Connections

Webhook nodes are starting points for workflows. They have no inputs, only outputs. Output to: Backend nodes:

Query nodes (fetch data based on webhook input)
Mutation nodes (create/update/delete based on webhook data)
Agent nodes (AI processing of webhook data)
HTTP Request nodes (forward to external APIs)
For Loop nodes (batch process webhook arrays)
If-Else nodes (conditional webhook logic)

Must connect to:

Return node (to send response back to caller)

Cannot connect to:

Frontend Element nodes (webhook is the trigger, not a UI element)

Webhook vs Other Triggers

Feature	Webhook Node	Frontend Element	Cron Node
Trigger	HTTP request	User action	Time-based
Input Data	body/params/headers/query	Form/UI data	None ()
Runs When	On API call	On user click	On schedule
Environment	Always	Always	Deployed only
Return Node	Yes	Yes	No
Authentication	Multiple types	Session-based	N/A
Use Case	External integrations	User interactions	Automation

Query Node

Fetch data based on webhook input

Mutation Node

Create/update data from webhooks

Return Node

Send response back to webhook caller

HTTP Request Node

Forward webhook data to external APIs

​Overview

​Required Configuration

​Basic Settings

​Authentication

​None

​Basic Auth

​Bearer Token

​Header Auth

​Query Parameter Auth

​Response Mode

​How It Works

​Step 1: Create the Trigger

​Step 2: Configure the Endpoint

​Step 3: Build Your Workflow

​Step 4: Access Webhook Data

​Accessing Webhook Data

​1. Request Body (POST/PUT/PATCH)

​2. Query Parameters (All Methods)

​3. URL Path Parameters

​4. Request Headers

​5. HTTP Method

​Common Use Cases

​1. Create Resource from External Service

​2. Query Data via API

​3. Update Resource with Path Parameters

​4. AI Processing from External Call

​5. Conditional Webhook Processing

​6. Batch Processing from API

​7. Proxy to External API

​Important Notes

​Webhook is a Start Node

​No Frontend Node Needed

​Security Best Practices

​Response Modes Guide

​Unique Endpoints

​Connections

​Webhook vs Other Triggers

​Related Nodes