Connect your agent to external services via webhooks.

What is a Webhook Tool?

A webhook tool lets your agent call external HTTP endpoints. When the agent invokes the tool, your service receives the arguments and can return results asynchronously.

Adding a Webhook Tool

1. Go to Tools tab
2. Click Add Tool → Webhook Tool
3. Fill in:
   • Name: Tool name (e.g., send-email)
   • Description: What the agent sees
   • URL: Your webhook endpoint
   • Secret: Optional authentication header
   • Input Schema: Optional JSON schema for parameters

What Your Webhook Receives

When the agent calls the hook, your endpoint receives a POST with:

1{2  "tool_invocation_id": "abc123",3  "hook_name": "send-email",4  "chat_id": "chat_xyz",5  "agent_id": "agent_123",6  "agent_version_id": "v1",7  "callback_url": "/api/tools/abc123",8  "callback_method": "POST",9  "timestamp": "2024-01-15T10:30:00Z",10  "arguments": {11    "to": "[email protected]",12    "subject": "Hello",13    "body": "Message content"14  }15}

Headers include:

• Content-Type: application/json
• X-Hook-Secret: your-secret (if configured)

Responding Immediately

Return a success acknowledgment:

1{2  "success": true,3  "message": "Processing"4}

The tool is now in "awaiting input" state.

Completing the Tool

When done, POST to the callback URL:

1{2  "result": "Email sent successfully to [email protected]"3}

The agent receives this and continues.

Input Schema

Define what parameters the agent can pass:

1{2  "type": "object",3  "properties": {4    "to": {5      "type": "string",6      "description": "Recipient email address"7    },8    "subject": {9      "type": "string", 10      "description": "Email subject line"11    },12    "body": {13      "type": "string",14      "description": "Email body content"15    }16  },17  "required": ["to", "subject", "body"]18}

If not provided, the agent sends a generic data object.

Use Cases

Security

• Use the secret header to verify requests
• Validate the callback URL matches expected patterns
• Sanitize arguments before use
• Set appropriate timeouts

Next

→ Chatting with Agents