Webhook Management

Webhook endpoints allow tools to communicate with external APIs. Configure endpoints once in settings, then reference them by name in your tools for portable, environment-independent integrations.

Why Use Endpoint Configuration?

Instead of hardcoding URLs in tools:

// Avoid this
{ "type": "webhook", "url": "https://api.prod.example.com/meals" }

Reference configured endpoints:

// Do this instead
{ "type": "webhook", "endpoint": "save_meal" }

Benefits

Accessing Endpoint Settings

1. Navigate to Settings in the dashboard
2. Click Manage Endpoints under Webhook Endpoints
3. Or go directly to /dashboard/settings/endpoints

Configuration Interface

API Base URL

Set the base URL for all endpoints:

https://api.example.com

Individual endpoint paths are appended to this base URL.

Example:

• Base URL: https://api.example.com
• Endpoint path: /api/v1/meals
• Full URL: https://api.example.com/api/v1/meals

Endpoints List

Each endpoint has:

• Name - Identifier used in tools
• Method - HTTP method (GET, POST, PUT, PATCH, DELETE)
• Path - URL path appended to base URL
• Headers - Custom headers (e.g., Authorization)

Adding an Endpoint

1. Enter a name in the input field (e.g., save_meal)
   • Lowercase letters, numbers, underscores only
   • Names are auto-formatted as you type
2. Click Add Endpoint
3. Expand the new endpoint to configure it

Configuring an Endpoint

Click on an endpoint to expand its configuration:

Method

Select the HTTP method:

Path

Enter the API path:

/api/v1/meals
/users/{{user.id}}/preferences

The full URL is shown below for verification.

Headers

Add custom headers for authentication and configuration:

1. Click Add Header
2. Enter header name (e.g., Authorization)
3. Enter header value (e.g., Bearer {{api_key}})
4. Add more headers as needed

Common headers:

Testing Endpoints

Click the test tube icon to verify connectivity:

1. Sends a request to the configured URL
2. Shows success (green check) or failure (red X)
3. Displays response status in toast notification

Note: Testing uses the exact configuration, so ensure headers are properly set.

Using Endpoints in Tools

Reference endpoints by name in webhook actions:

{
  "type": "webhook",
  "endpoint": "save_meal",
  "payload": {
    "meal_type": "params.meal_type",
    "dishes": "params.dishes",
    "timestamp": "context.current_time"
  },
  "result_key": "api_response"
}

Payload Mapping

Map tool parameters and context to the request body:

Storing Results

Use result_key to store the API response in context:

{
  "type": "webhook",
  "endpoint": "get_user",
  "result_key": "api_user"
}

Access the result in subsequent actions:

{
  "type": "respond",
  "message": "Welcome back, {{context.api_user.name}}!"
}

Environment Management

Development Setup

Configure endpoints for local development:

Base URL: http://localhost:3000

Staging/Production

Update base URL for each environment:

Base URL: https://api.staging.example.com
Base URL: https://api.example.com

Tools automatically use the correct endpoints based on tenant configuration.

Common Patterns

REST API Integration

Endpoint: create_order
Method: POST
Path: /api/v1/orders

Endpoint: get_order
Method: GET
Path: /api/v1/orders/{{order_id}}

Endpoint: update_order
Method: PATCH
Path: /api/v1/orders/{{order_id}}

Authenticated API

Endpoint: secure_api
Method: POST
Path: /api/v1/secure
Headers:
  Authorization: Bearer {{tenant.api_token}}
  X-Request-ID: {{call.id}}

Third-Party Services

Endpoint: send_notification
Method: POST
Path: /v1/messages
Headers:
  Authorization: Key {{twilio_key}}
  Content-Type: application/json

Error Handling

When webhook calls fail:

1. Error is logged with request details
2. Tool's on_failure actions execute
3. Context contains error information

Handle errors in tools:

{
  "on_failure": [
    {
      "type": "log",
      "level": "error",
      "message": "Webhook failed",
      "data": "error"
    },
    {
      "type": "respond",
      "message": "I'm having trouble saving that. Let me try again."
    }
  ]
}

Security Best Practices

API Keys

1. Never hardcode secrets in tool configurations
2. Use tenant settings for API keys
3. Reference via context: {{tenant.api_key}}

HTTPS

1. Always use HTTPS for production endpoints
2. HTTP allowed only for local development
3. Base URL should start with https://

Minimal Headers

1. Only include necessary headers
2. Don't expose internal tokens to logs
3. Rotate credentials regularly

Troubleshooting

Connection Errors

Authentication Errors

Response Errors