The Webhook Node allows your agent to communicate with external systems by making HTTP requests to APIs and services.

​
Purpose & Functionality

Makes HTTP requests to external services. Primarily used for sending/receiving data via APIs. Can use response data in subsequent steps or trigger notifications (based on its prompt).

Does not typically pause for user input itself, although its prompt could instruct it to ask a follow-up question based on the webhook result, which would cause a pause.

​
Configuration

  • Name: A label for the node on the Canvas
  • URL: The endpoint to call (required). Supports variable interpolation using #{variable} syntax.
  • HTTP Method: GET, POST, PUT, PATCH, DELETE (required)
  • Headers: JSON object of request headers (defaults to {}). Supports variable interpolation using #{variable} syntax.
  • Body Schema: JSON Schema defining the structure of the request body, used for validation and documentation. This is the preferred way to define request bodies.
  • Request Body: JSON object of request data (defaults to {}). Note: This field is being deprecated in favor of Body Schema.
  • JMESPath Query: (Optional) Query to transform and filter the webhook response before passing it to the agent.
  • Mock Response Enabled: Boolean. If true, the node will return the Mock Response instead of making a real HTTP request (defaults to false)
  • Mock Response: JSON object. The response to return when Mock Response Enabled is true (defaults to {})
  • Prompt: Instructions for handling the webhook response

​
Body Schema

The Body Schema defines the structure, types, and required fields for your webhook request body using JSON Schema format. This is now the preferred way to define request bodies, replacing the older Request Body field. Benefits include:

  • Documentation for API consumers
  • Runtime validation of request data
  • Better developer experience with schema-based editors
  • Support for variable interpolation in the generated requests

Example body schema:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Unique identifier for the order"
    },
    "items": {
      "type": "array",
      "description": "List of items in the order",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          }
        }
      }
    }
  },
  "required": ["order_id"]
}

​
Variable Interpolation

You can insert dynamic values into your URLs, headers, and generated request bodies using the #{variable} syntax:

  • https://api.example.com/users/#{user_id} - Inserts the user_id variable into the URL
  • "Authorization": "Bearer #{api_token}" - Inserts the api_token variable into the headers
  • Body schemas will generate requests that also support variable interpolation

These variables can come from:

  • Conversation context
  • Previous node outputs
  • Graph-level variables

​
Use Cases

  • Integrating with external APIs
  • Triggering external workflows
  • Fetching data from backend systems
  • Updating records in external databases
  • Sending notifications to other systems

​
Example

Configuration:

{
  "url": "https://api.example.com/inventory/#{product_id}",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer #{api_token}",
    "Content-Type": "application/json"
  },
  "body_schema": {
    "type": "object",
    "properties": {
      "product_id": {
        "type": "string",
        "description": "The ID of the product to check"
      },
      "store_location": {
        "type": "string",
        "description": "Store location code"
      }
    },
    "required": ["product_id"]
  }
}

Prompt:

Check if the requested product is in stock by looking at the webhook response.
If it's in stock, inform the customer about availability.
If it's out of stock, ask if they would like to be notified when it's available.

​
Best Practices

  • Use variables (#{variable}) in URLs and headers for dynamic values
  • Define comprehensive body schemas instead of using the deprecated body field
  • Provide mock responses during development and testing
  • Handle errors gracefully in your prompts
  • Use the visual schema editor to build complex request body structures

Default Node

The most versatile node for general conversation

WhatsApp Template Node

Send pre-approved WhatsApp message templates

Knowledge Base Node

Access specific knowledge sources for responses