Skip to main content

​
Description

WebhookStep enables your agents to make HTTP calls to external APIs and services. Use webhooks to trigger actions, send notifications, update external systems, or retrieve data from REST APIs.

​
WebhookStep

webhook:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/endpoint"
    method: POST
    auth_token: "${API_TOKEN}"
    timeout: 30
  input_mapping:
    context_data: data_node#output

​
Configuration Parameters

ParameterTypeRequiredDefaultDescription
webhook_urlstrYes-The URL to call
methodHttpMethodNoPOSTHTTP method (GET, POST, PUT, DELETE, PATCH)
auth_tokenstrNo-Bearer token for authentication
timeoutintNo30Request timeout in seconds
retriesintNo2Number of retry attempts
static_headersDictNo-Additional HTTP headers
webhook_namestrNo"webhook-step"Identifier for logging

​
HTTP Methods

# GET request
get_data:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/users/${user_id}"
    method: GET
    auth_token: "${API_TOKEN}"

# POST request
create_ticket:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/tickets"
    method: POST
    auth_token: "${API_TOKEN}"
  input_mapping:
    context_data: ticket_data#output

# PUT request
update_record:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/records/${record_id}"
    method: PUT
    auth_token: "${API_TOKEN}"
  input_mapping:
    context_data: updated_data#output

​
Authentication

​
Bearer Token

config:
  auth_token: "${API_TOKEN}"

​
Custom Headers

config:
  static_headers:
    Authorization: "Basic ${ENCODED_CREDENTIALS}"
    X-API-Key: "${API_KEY}"
    Content-Type: "application/json"

​
Input Data

The context_data input is sent as the request body for POST/PUT/PATCH requests: 
nodes:
  # Prepare the data to send
  prepare_data:
    type: JSONCreatorStep
    config:
      schema: '{"customer_id": $customer_id, "message": $message, "priority": "high"}'
    input_mapping:
      customer_id: extract#customer_id
      message: generate#response

  # Send via webhook
  send_notification:
    type: WebhookStep
    config:
      webhook_url: "https://api.example.com/notifications"
      method: POST
      auth_token: "${API_TOKEN}"
    input_mapping:
      context_data: prepare_data#json

​
Outputs

OutputTypeDescription
webhook_resultOptional[Dict[str, Any]]The JSON response from the webhook

​
Example: Trigger External Action

nodes:
  # Generate a response
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals

  # Log the interaction to an external system
  log_interaction:
    type: WebhookStep
    config:
      webhook_url: "https://analytics.example.com/log"
      method: POST
      auth_token: "${ANALYTICS_TOKEN}"
      static_headers:
        X-Source: "contextual-agent"
    input_mapping:
      context_data: interaction_data#json

  __outputs__:
    type: output
    input_mapping:
      response: generate#response

​
Example: Fetch External Data

nodes:
  # Get real-time data from external API
  fetch_prices:
    type: WebhookStep
    config:
      webhook_url: "https://api.pricing.example.com/current"
      method: GET
      auth_token: "${PRICING_TOKEN}"
      timeout: 10

  # Use the data in generation
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals
      pricing_data: fetch_prices#webhook_result

​
Error Handling

WebhookStep includes automatic retry logic. Configure retries and timeout: 
config:
  webhook_url: "https://api.example.com/endpoint"
  timeout: 60        # Wait up to 60 seconds
  retries: 3         # Retry up to 3 times on failure