Call external HTTP endpoints as agent tools.
Authenticated REST APIs: For bearer tokens, API keys, or OAuth credentials injected by the runtime, use Call Tools instead. In the JavaScript SDK, define these with
httpTool()orcallTool()(aliases). Python usescall_tool(). Webhook tools are for endpoints that accept a POST body from inference shell (optionally HMAC-signed with.secret()).
Basic Usage
1from inferencesh import webhook_tool, string23inventory = (4 webhook_tool("check_inventory", "https://api.example.com/inventory")5 .describe("Check product inventory levels")6 .param("sku", string("Product SKU"))7 .build()8)How It Works
When the agent calls a webhook tool:
- inference shell sends a POST request to your URL
- Request body contains tool arguments as JSON
- Your server processes and returns JSON response
- Response becomes the tool result
Builder Methods
| Method | Description |
|---|---|
webhookTool(name, url) | Create webhook tool |
.describe(text) | Set description for LLM |
.display(name) | Human-readable name |
.param(name, schema) | Define expected parameters |
.secret(key) | Signing secret for verification |
.requireApproval() | Require user approval |
.build() | Build the tool |
Request Format
Your endpoint receives:
1POST /your-endpoint2Content-Type: application/json3X-Webhook-Signature: sha256=...45{6 "sku": "WIDGET-123"7}Response Format
Return JSON:
1{2 "in_stock": true,3 "quantity": 42,4 "warehouse": "NYC"5}Webhook Signing
Verify requests are from inference shell:
1webhook = (2 webhook_tool("secure_action", "https://api.example.com/action")3 .describe("Perform a secure action")4 .secret("your_webhook_secret") # Secret for HMAC signing5 .build()6)When an agent version is saved, each hook secret and each literal HTTP header value is stored as an internal encrypted secret of the version's team, and the tool keeps a reference to it. It is not a row in your Secrets list, and reading the agent does not return the value.
Verifying Signatures
1import hmac2import hashlib34def verify_signature(payload: bytes, signature: str, secret: str) -> bool:5 expected = hmac.new(6 secret.encode(),7 payload,8 hashlib.sha2569 ).hexdigest()10 return hmac.compare_digest(f"sha256={expected}", signature)With Parameters
1from inferencesh import webhook_tool, string, number, obj23order_api = (4 webhook_tool("create_order", "https://api.example.com/orders")5 .describe("Create a new order in the system")6 .param("product", string("Product name"))7 .param("quantity", number("Order quantity"))8 .param("customer", obj({9 "name": string("Customer name"),10 "email": string("Customer email")11 }, "Customer details"))12 .secret("order_webhook_secret")13 .require_approval() # Orders need approval14 .build()15)Example Server
1from fastapi import FastAPI, Request, Header2import hmac3import hashlib45app = FastAPI()67@app.post("/inventory")8async def check_inventory(9 request: Request,10 x_webhook_signature: str = Header(None)11):12 body = await request.body()13 14 # Verify signature15 if not verify_signature(body, x_webhook_signature, "your_secret"):16 return {"error": "Invalid signature"}, 40117 18 data = await request.json()19 sku = data["sku"]20 21 # Your logic here22 return {23 "in_stock": True,24 "quantity": 4225 }