# Webhooks

> Connect your agent to external services via webhooks.

**URL:** https://inference.sh/docs/agents/webhooks
**Last updated:** 2026-10-11

---

Connect your agent to external services via webhooks.

---

## Agent webhook tools vs task completion webhooks

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

| | **Agent webhook tool** (this page) | **Task completion webhook** |
|---|-----------------------------------|-----------------------------|
| **Purpose** | Let an agent call *your* HTTP endpoint as a tool during a chat | Notify *your* server when an app or flow **task** finishes |
| **Configured on** | Agent → Tools → Webhook Tool | `webhook` field on `POST /run` (REST or SDK) |
| **When it fires** | Each time the agent invokes the tool | Once per task, on terminal status (completed, failed, cancelled) |
| **Your server** | Receives tool args; may POST results back via `callback_url` | Receives `{event, timestamp, data}` with the task result (`id`, `status`, `output`, …) in `data` |

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](/docs/api/rest/tasks#webhooks)  
→ [Running Apps (SDK) — Webhooks](/docs/api/sdk/running-apps)  
→ [Tasks concept — Webhooks](/docs/concepts/tasks) *(completion notifications)*  
→ [Webhook Tools (SDK)](/docs/api/agent/webhook-tools) — 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:

```json
{
  "tool_invocation_id": "abc123",
  "hook_name": "send-email",
  "chat_id": "chat_xyz",
  "agent_id": "agent_123",
  "agent_version_id": "v1",
  "callback_url": "/api/tools/abc123",
  "callback_method": "POST",
  "timestamp": "2024-01-15T10:30:00Z",
  "arguments": {
    "to": "user@example.com",
    "subject": "Hello",
    "body": "Message content"
  }
}
```

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

---

## Responding Immediately

Return a success acknowledgment:

```json
{
  "success": true,
  "message": "Processing"
}
```

The tool is now in "awaiting input" state.

---

## Completing the Tool

When done, POST to the callback URL:

```json
{
  "result": "Email sent successfully to user@example.com"
}
```

The agent receives this and continues.

---

## Input Schema

Define what parameters the agent can pass:

```json
{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "description": "Recipient email address"
    },
    "subject": {
      "type": "string", 
      "description": "Email subject line"
    },
    "body": {
      "type": "string",
      "description": "Email body content"
    }
  },
  "required": ["to", "subject", "body"]
}
```

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

---

## Use Cases

| Hook | Purpose |
|------|---------|
| `send-email` | Send emails via your SMTP |
| `create-ticket` | Create support tickets |
| `notify-slack` | Post to Slack channels |
| `run-script` | Execute custom scripts |
| `query-database` | Run database queries |

---

## 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](/docs/agents/chatting)