Call external HTTP endpoints as agent tools.
Basic Usage
1from inferencesh import webhook_tool, string2 3inventory = (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.sh 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:
json
1POST /your-endpoint2Content-Type: application/json3X-Webhook-Signature: sha256=...4 5{6 "sku": "WIDGET-123"7}Response Format
Return JSON:
json
1{2 "in_stock": true,3 "quantity": 42,4 "warehouse": "NYC"5}Webhook Signing
Verify requests are from inference.sh:
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)Verifying Signatures
1import hmac2import hashlib3 4def 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, obj2 3order_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 hashlib4 5app = FastAPI()6 7@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 }