Webhook Tools

Tools allow your AI agent to execute actions by calling your webhooks. The LLM decides when to use a tool based on the conversation context, executes the call, and uses the result in its response.

What are Agent Tools?

A Tool is a webhook endpoint that your agent can call to perform actions or retrieve data. When you define a tool, you specify:

Name: How the agent refers to the tool
Description: When the agent should use it
Parameters: What data to send (JSON Schema)
Webhook URL: Your endpoint that handles the request

The AI model uses the description to decide when to invoke the tool automatically.

Use Cases

Tool	Description	Example Use
`check_order_status`	Look up order tracking info	”Where is my order #12345?”
`create_support_ticket`	Open a support ticket	”I need help with my account”
`book_appointment`	Schedule a calendar event	”Book me for next Tuesday at 2pm”
`get_inventory`	Check product availability	”Do you have the blue shirt in medium?”
`lookup_customer`	Retrieve customer data	”What’s my account balance?”
`process_refund`	Initiate a refund	”I want a refund for order #123”

Via Dashboard

Navigate to Tools

Go to Senders > select your sender > Agent tab > Tools section.

Create New Tool

Click Create Tool and fill in the form:

Name: A short identifier (e.g., check_order_status)
Description: When should the agent use this tool? Be specific.
Webhook URL: Your HTTPS endpoint

Define Parameters

Specify the parameters your webhook expects:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID to look up"
    }
  },
  "required": ["order_id"]
}

Configure Security (Optional)

Add a Webhook Secret to verify requests are from Zavu. We’ll sign each request with this secret.

Test the Tool

Use the Test button to send a sample request to your webhook and verify it responds correctly.

Enable the Tool

Toggle the tool to Enabled so the agent can use it.

Via API

Create Tool

import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

const tool = await zavu.senders.agent.tools.create("sender_abc123", {
  name: "check_order_status",
  description: "Look up the status and tracking information for a customer order. Use this when a customer asks about their order status, shipping, or delivery.",
  parameters: {
    type: "object",
    properties: {
      order_id: {
        type: "string",
        description: "The order ID (e.g., ORD-12345)",
      },
    },
    required: ["order_id"],
  },
  webhookUrl: "https://api.yourcompany.com/webhooks/order-status",
  webhookSecret: "whsec_your_secret_here", // Optional
});

console.log("Tool created:", tool.id);

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

tool = zavu.senders.agent.tools.create(
    "sender_abc123",
    name="check_order_status",
    description="Look up the status and tracking information for a customer order. Use this when a customer asks about their order status, shipping, or delivery.",
    parameters={
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "The order ID (e.g., ORD-12345)",
            },
        },
        "required": ["order_id"],
    },
    webhook_url="https://api.yourcompany.com/webhooks/order-status",
    webhook_secret="whsec_your_secret_here",  # Optional
)

print(f"Tool created: {tool.id}")

require "zavudev"

client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

tool = client.senders.agent.tools.create("sender_abc123",
  name: "check_order_status",
  description: "Look up the status and tracking information for a customer order. Use this when a customer asks about their order status, shipping, or delivery.",
  parameters: {
    type: "object",
    properties: {
      order_id: {
        type: "string",
        description: "The order ID (e.g., ORD-12345)"
      }
    },
    required: ["order_id"]
  },
  webhook_url: "https://api.yourcompany.com/webhooks/order-status",
  webhook_secret: "whsec_your_secret_here" # Optional
)

puts "Tool created: #{tool.id}"

tool, _ := client.Senders.Agent.Tools.Create(context.TODO(), "sender_abc123", zavudev.ToolCreateParams{
	Name:        zavudev.String("check_order_status"),
	Description: zavudev.String("Look up the status and tracking information for a customer order. Use this when a customer asks about their order status, shipping, or delivery."),
	Parameters: &zavudev.ToolParameters{
		Type: zavudev.String("object"),
		Properties: map[string]interface{}{
			"order_id": map[string]interface{}{
				"type":        "string",
				"description": "The order ID (e.g., ORD-12345)",
			},
		},
		Required: []string{"order_id"},
	},
	WebhookURL:    zavudev.String("https://api.yourcompany.com/webhooks/order-status"),
	WebhookSecret: zavudev.String("whsec_your_secret_here"), // Optional
})

fmt.Printf("Tool created: %s\n", tool.ID)

$tool = $client->senders->agent->tools->create('sender_abc123', [
    'name' => 'check_order_status',
    'description' => 'Look up the status and tracking information for a customer order. Use this when a customer asks about their order status, shipping, or delivery.',
    'parameters' => [
        'type' => 'object',
        'properties' => [
            'order_id' => [
                'type' => 'string',
                'description' => 'The order ID (e.g., ORD-12345)',
            ],
        ],
        'required' => ['order_id'],
    ],
    'webhookUrl' => 'https://api.yourcompany.com/webhooks/order-status',
    'webhookSecret' => 'whsec_your_secret_here', // Optional
]);

echo "Tool created: {$tool->id}\n";

curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent/tools \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order_status",
    "description": "Look up the status and tracking information for a customer order.",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order ID (e.g., ORD-12345)"
        }
      },
      "required": ["order_id"]
    },
    "webhookUrl": "https://api.yourcompany.com/webhooks/order-status",
    "webhookSecret": "whsec_your_secret_here"
  }'

List Tools

const tools = await zavu.senders.agent.tools.list("sender_abc123");

for (const tool of tools.items) {
  console.log(`${tool.name} - ${tool.enabled ? "Enabled" : "Disabled"}`);
}

tools = zavu.senders.agent.tools.list("sender_abc123")

for tool in tools.items:
    status = "Enabled" if tool.enabled else "Disabled"
    print(f"{tool.name} - {status}")

tools = client.senders.agent.tools.list("sender_abc123")

tools.items.each do |tool|
  status = tool.enabled ? "Enabled" : "Disabled"
  puts "#{tool.name} - #{status}"
end

tools, _ := client.Senders.Agent.Tools.List(context.TODO(), "sender_abc123", zavudev.ToolListParams{})

for _, tool := range tools.Items {
	status := "Disabled"
	if tool.Enabled {
		status = "Enabled"
	}
	fmt.Printf("%s - %s\n", tool.Name, status)
}

$tools = $client->senders->agent->tools->list('sender_abc123');

foreach ($tools->items as $tool) {
    $status = $tool->enabled ? 'Enabled' : 'Disabled';
    echo "{$tool->name} - {$status}\n";
}

curl https://api.zavu.dev/v1/senders/sender_abc123/agent/tools \
  -H "Authorization: Bearer $ZAVU_API_KEY"

Update Tool

const tool = await zavu.senders.agent.tools.update(
  "sender_abc123",
  "tool_xyz789",
  {
    description: "Updated description for better AI understanding",
    enabled: true,
  }
);

tool = zavu.senders.agent.tools.update(
    "sender_abc123",
    "tool_xyz789",
    description="Updated description for better AI understanding",
    enabled=True,
)

tool = client.senders.agent.tools.update("sender_abc123", "tool_xyz789",
  description: "Updated description for better AI understanding",
  enabled: true
)

tool, _ := client.Senders.Agent.Tools.Update(context.TODO(), "sender_abc123", "tool_xyz789", zavudev.ToolUpdateParams{
	Description: zavudev.String("Updated description for better AI understanding"),
	Enabled:     zavudev.Bool(true),
})

$tool = $client->senders->agent->tools->update('sender_abc123', 'tool_xyz789', [
    'description' => 'Updated description for better AI understanding',
    'enabled' => true,
]);

curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent/tools/tool_xyz789 \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "enabled": true}'

Delete Tool

await zavu.senders.agent.tools.delete("sender_abc123", "tool_xyz789");

zavu.senders.agent.tools.delete("sender_abc123", "tool_xyz789")

client.senders.agent.tools.delete("sender_abc123", "tool_xyz789")

client.Senders.Agent.Tools.Delete(context.TODO(), "sender_abc123", "tool_xyz789")

$client->senders->agent->tools->delete('sender_abc123', 'tool_xyz789');

curl -X DELETE https://api.zavu.dev/v1/senders/sender_abc123/agent/tools/tool_xyz789 \
  -H "Authorization: Bearer $ZAVU_API_KEY"

Webhook Payload

When the agent invokes a tool, your webhook receives a POST request:

{
  "tool": "check_order_status",
  "arguments": {
    "order_id": "ORD-12345"
  },
  "context": {
    "messageId": "msg_abc123",
    "contactPhone": "+14155551234",
    "sessionId": "session_xyz789"
  },
  "timestamp": 1703001234567
}

Headers

Header	Description
`Content-Type`	`application/json`
`X-Zavu-Tool`	Tool name being invoked
`X-Zavu-Timestamp`	Unix timestamp of the request
`X-Zavu-Signature`	HMAC-SHA256 signature (if webhook secret is configured)

Webhook Response

Your webhook should return JSON with the result:

{
  "status": "shipped",
  "carrier": "FedEx",
  "trackingNumber": "7891234567890",
  "estimatedDelivery": "2024-01-15"
}

The agent will incorporate this data into its response to the user.

Error Responses

Return appropriate HTTP status codes for errors:

{
  "error": "Order not found",
  "code": "ORDER_NOT_FOUND"
}

The agent will handle errors gracefully and inform the user appropriately.

Signature Verification

If you configured a webhook secret, verify the signature to ensure requests are from Zavu:

import crypto from "crypto";

function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post("/webhooks/order-status", (req, res) => {
  const signature = req.headers["x-zavu-signature"];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Process the request...
});

import hmac
import hashlib

def verify_signature(payload: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your webhook handler (Flask example)
@app.route("/webhooks/order-status", methods=["POST"])
def handle_order_status():
    signature = request.headers.get("X-Zavu-Signature")
    payload = request.get_data(as_text=True)

    if not verify_signature(payload, signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    # Process the request...

require "openssl"

def verify_signature(payload, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
  Rack::Utils.secure_compare(signature, expected)
end

# In your webhook handler (Sinatra example)
post "/webhooks/order-status" do
  signature = request.env["HTTP_X_ZAVU_SIGNATURE"]
  payload = request.body.read

  unless verify_signature(payload, signature, ENV["WEBHOOK_SECRET"])
    halt 401, { error: "Invalid signature" }.to_json
  end

  # Process the request...
end

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
)

func verifySignature(payload, signature, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(payload))
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(signature), []byte(expected))
}

// In your webhook handler
http.HandleFunc("/webhooks/order-status", func(w http.ResponseWriter, r *http.Request) {
	signature := r.Header.Get("X-Zavu-Signature")
	body, _ := io.ReadAll(r.Body)

	if !verifySignature(string(body), signature, os.Getenv("WEBHOOK_SECRET")) {
		http.Error(w, `{"error":"Invalid signature"}`, http.StatusUnauthorized)
		return
	}

	// Process the request...
})

function verifySignature(string $payload, string $signature, string $secret): bool {
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

// In your webhook handler
$signature = $_SERVER['HTTP_X_ZAVU_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');

if (!verifySignature($payload, $signature, getenv('WEBHOOK_SECRET'))) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Process the request...

Tool Execution Flow

Customer: "Where is my order #12345?"
                    |
                    v
            +---------------+
            |   AI Agent    |
            | Analyzes msg  |
            +---------------+
                    |
                    v
            +---------------+
            | Decides to    |
            | use tool      |
            +---------------+
                    |
                    v
            +---------------+
            | Calls webhook |
            | with order_id |
            +---------------+
                    |
                    v
            +---------------+
            | Your Server   |
            | Returns data  |
            +---------------+
                    |
                    v
            +---------------+
            | AI formulates |
            | response      |
            +---------------+
                    |
                    v
Customer: "Your order #12345 shipped via FedEx
           and will arrive January 15th."

Best Practices

Write Clear Descriptions

The AI uses the description to decide when to use the tool. Be specific about when it should and shouldn’t be used.

Use HTTPS

Webhook URLs must use HTTPS for security. We reject HTTP endpoints.

Handle Errors Gracefully

Return meaningful error messages so the agent can inform the user appropriately.

Respond Quickly

Keep webhook response times under 10 seconds. The user is waiting for a response.

Example Tool Descriptions

Good description:

Look up the status and tracking information for a customer order.
Use when the customer asks about their order status, shipping progress,
delivery estimate, or tracking number. Requires the order ID which
typically starts with "ORD-" followed by numbers.

Poor description:

Get order info.

Poor descriptions lead to tools being used incorrectly or not at all. Invest time in writing clear, detailed descriptions.

Security Considerations

Always use HTTPS for webhook endpoints
Verify signatures using the webhook secret
Validate parameters before processing
Rate limit your webhook endpoints
Log requests for debugging and auditing
Never expose sensitive data in tool responses that shouldn’t be shared with customers

Getting Started

Concepts

Guides

Webhook Tools

Webhook Tools

What are Agent Tools?

Use Cases

Via Dashboard

Via API

Create Tool

List Tools

Update Tool

Delete Tool

Webhook Payload

Headers

Webhook Response

Error Responses

Signature Verification

Tool Execution Flow

Best Practices

Write Clear Descriptions

Use HTTPS

Handle Errors Gracefully

Respond Quickly

Example Tool Descriptions

Security Considerations

Next Steps

Add Knowledge Base

Create Flows

​Webhook Tools

​What are Agent Tools?

​Use Cases

​Via Dashboard

​Via API

​Create Tool

​List Tools

​Update Tool

​Delete Tool

​Webhook Payload

​Headers

​Webhook Response

​Error Responses

​Signature Verification

​Tool Execution Flow

​Best Practices

Write Clear Descriptions

Use HTTPS

Handle Errors Gracefully

Respond Quickly

​Example Tool Descriptions

​Security Considerations

​Next Steps

Add Knowledge Base

Create Flows

Webhook Tools

What are Agent Tools?

Use Cases

Via Dashboard

Via API

Create Tool

List Tools

Update Tool

Delete Tool

Webhook Payload

Headers

Webhook Response

Error Responses

Signature Verification

Tool Execution Flow

Best Practices

Example Tool Descriptions

Security Considerations

Next Steps