> ## Documentation Index > Fetch the complete documentation index at: https://docs.vibeflow.ai/llms.txt > Use this file to discover all available pages before exploring further. # Webhook Node > Create REST API endpoints to trigger workflows from external services ## 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 ` #### 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: ` or `X-API-Key: Bearer ` #### 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=` ### 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 1. Set the HTTP method (POST for data creation, GET for retrieval, etc.) 2. Define the webhook path (e.g., "/users/create") 3. Choose authentication method to secure the endpoint 4. 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.` **Example:** POST request with body `{ "name": "John", "email": "john@example.com" }` ```json theme={null} // 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.` **Example:** GET request to `/users?status=active&limit=10` ```json theme={null} // 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.` **Example:** PATCH request to `/users/:userId` ```json theme={null} // 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.
` or `$"startNode".headers["header-name"]` **Example:** Access custom request ID header ```json theme={null} // 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 ```json theme={null} // 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 | ## Related Nodes Fetch data based on webhook input Create/update data from webhooks Send response back to webhook caller Forward webhook data to external APIs