Webhooks

Connect your agent to external services via webhooks.

Agent webhook tools vs task completion webhooks

inference.sh uses webhooks in two different places. They are not interchangeable.

Use webhook tools when the agent should reach your API mid-conversation (send email, create ticket, run a script).

Use task webhooks for fire-and-forget app runs — submit work, close the client, get a POST when done.

→ Tasks API — Webhooks
→ Running Apps (SDK) — Webhooks
→ Tasks concept — Webhooks (completion notifications)
→ Webhook Tools (SDK) — define webhook tools in code

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