Webhook Tools API

Webhook tools allow your AI agent to call external APIs during conversations. Define custom tools that the agent can use to fetch data, perform actions, or integrate with your systems.

How Webhook Tools Work

You define a tool with a name, description, and input schema
The AI agent decides when to use the tool based on the conversation
When triggered, Fig1 calls your webhook endpoint with the tool inputs
Your endpoint returns data that the agent uses in its response

User: "What's the status of order #12345?"
         ↓
Agent recognizes: needs order info
         ↓
Calls webhook: GET https://your-api.com/orders?id=12345
         ↓
Your API returns: { "status": "shipped", "tracking": "1Z999..." }
         ↓
Agent responds: "Order #12345 has shipped! Tracking: 1Z999..."

GET /api/sdk/webhook-tools

List all webhook tools configured for your site.

Example Request

curl -X GET "https://app.fig1.ai/api/sdk/webhook-tools" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

Response

{
  "success": true,
  "data": [
    {
      "_id": "tool_abc123",
      "name": "check_inventory",
      "description": "Check product inventory levels by SKU",
      "inputSchema": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU to check"
          }
        },
        "required": ["sku"]
      },
      "endpoint": "https://your-api.com/inventory",
      "method": "GET",
      "enabled": true
    }
  ]
}

POST /api/sdk/webhook-tools

Create a new webhook tool.

Request Body

{
  name: string;              // Unique identifier (lowercase, underscores allowed)
  description: string;       // When should the agent use this tool?

  inputSchema: {             // JSON Schema for tool parameters
    type: 'object';
    properties: {
      [key: string]: {
        type: 'string' | 'number' | 'boolean' | 'array' | 'object';
        description: string;
        enum?: string[];     // Optional: limit to specific values
      };
    };
    required?: string[];     // Which properties are required
  };

  endpoint: string;          // Your webhook URL
  method: 'GET' | 'POST';    // HTTP method to use
  headers?: {                // Optional custom headers
    [key: string]: string;
  };
  resultPath?: string;       // JSONPath to extract from response
}

Example: Create Inventory Check Tool

curl -X POST https://app.fig1.ai/api/sdk/webhook-tools \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "name": "check_inventory",
    "description": "Check product inventory levels. Use when customers ask about stock, availability, or whether an item is in stock.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "sku": {
          "type": "string",
          "description": "The product SKU to check inventory for"
        },
        "warehouse": {
          "type": "string",
          "description": "Optional warehouse location",
          "enum": ["east", "west", "central"]
        }
      },
      "required": ["sku"]
    },
    "endpoint": "https://api.yourstore.com/inventory",
    "method": "GET"
  }'

Example: Create Order Lookup Tool

curl -X POST https://app.fig1.ai/api/sdk/webhook-tools \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "name": "lookup_order",
    "description": "Look up order status and details. Use when customers ask about their order, shipping status, or tracking information.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order ID or order number"
        },
        "email": {
          "type": "string",
          "description": "Customer email for verification (optional)"
        }
      },
      "required": ["order_id"]
    },
    "endpoint": "https://api.yourstore.com/orders/lookup",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your-internal-api-key"
    }
  }'

PUT /api/sdk/webhook-tools/:id

Update an existing webhook tool.

curl -X PUT https://app.fig1.ai/api/sdk/webhook-tools/tool_abc123 \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "description": "Updated description for better AI understanding",
    "enabled": true
  }'

DELETE /api/sdk/webhook-tools/:id

Delete a webhook tool.

curl -X DELETE https://app.fig1.ai/api/sdk/webhook-tools/tool_abc123 \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

Webhook Request Format

When your tool is triggered, Fig1 calls your endpoint:

GET Method

Parameters are passed as query string:

GET https://your-api.com/inventory?sku=ABC123&warehouse=east

POST Method

Parameters are passed as JSON body:

POST https://your-api.com/orders/lookup
Content-Type: application/json

{
  "order_id": "ORD-12345",
  "email": "customer@example.com"
}

Webhook Response Format

Your endpoint should return JSON. The agent will use the response to formulate its answer.

Simple Response

{
  "sku": "ABC123",
  "name": "Widget Pro",
  "inStock": true,
  "quantity": 47
}

Using resultPath

If your API wraps data, use resultPath to extract the relevant portion:

// Your API returns:
{
  "success": true,
  "data": {
    "order": {
      "id": "ORD-12345",
      "status": "shipped"
    }
  }
}

// With resultPath: "data.order", the agent receives:
{
  "id": "ORD-12345",
  "status": "shipped"
}

Writing Good Tool Descriptions

The description tells the AI when to use the tool. Be specific:

Good descriptions:

"Check product inventory levels. Use when customers ask about stock, availability, or whether an item is in stock."
"Look up order status and shipping information. Use when customers ask about their order, where their package is, or tracking."

Poor descriptions:

"Gets inventory" (too vague)
"Order tool" (doesn't explain when to use)

Security Considerations

Authentication: Use the headers field to pass API keys to your backend
Validation: Your webhook should validate the request is from Fig1
Rate Limiting: Implement rate limiting on your webhook endpoints
Error Handling: Return clear error messages the agent can relay to users

Error Responses

If your webhook fails, the agent will acknowledge the error gracefully:

// Your endpoint returns:
{
  "error": "Order not found"
}

// Agent responds:
"I couldn't find an order with that ID. Could you double-check the order number?"

Best Practices

Keep tools focused - One tool per task, not mega-tools that do everything
Use descriptive property names - order_id not oid
Provide property descriptions - Help the AI extract the right values
Test thoroughly - Verify your webhook handles all expected inputs
Monitor usage - Check the dashboard for tool call analytics