> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time events from your agents via outgoing webhooks with HMAC-SHA256 signing.

## Overview

Webhooks let you receive real-time HTTP notifications when events occur on your agents — chat messages, voice calls, campaign steps, and more. Register an HTTPS endpoint, choose which events to subscribe to, and ThinnestAI will POST signed JSON payloads to your URL.

## How It Works

1. **Register an endpoint** with a URL and event types
2. **Receive a signing secret** (shown once — save it)
3. **Events fire** as your agents operate
4. **ThinnestAI POSTs** signed JSON to your URL
5. **Verify the signature** to confirm authenticity
6. **Respond with 2xx** to acknowledge receipt

Failed deliveries are retried with exponential backoff (10s, 60s, 5min) up to 3 times.

## Event Types

| Event                     | Description                                 |
| ------------------------- | ------------------------------------------- |
| `agent.created`           | New agent created                           |
| `agent.updated`           | Agent configuration changed                 |
| `agent.deleted`           | Agent deleted                               |
| `chat.message.completed`  | Agent finished responding to a chat message |
| `chat.session.ended`      | Chat session ended                          |
| `voice.call.started`      | Voice call connected                        |
| `voice.call.ended`        | Voice call ended                            |
| `campaign.step.completed` | Campaign step executed                      |
| `campaign.completed`      | Campaign finished                           |
| `webhook.test`            | Test event (sent via API)                   |

## Payload Format

Every webhook POST has this JSON structure:

```json theme={null}
{
  "event": "chat.message.completed",
  "timestamp": "2026-03-16T10:30:00.000Z",
  "agent_id": 42,
  "data": {
    "session_id": "sess_abc123",
    "message": "Hello! How can I help?",
    "tokens_used": 150
  }
}
```

## Headers

Every webhook request includes these headers:

| Header                  | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `X-Webhook-Signature`   | `sha256=<hmac_hex>` — HMAC-SHA256 of `{timestamp}.{body}` |
| `X-Webhook-Timestamp`   | Unix timestamp (seconds)                                  |
| `X-Webhook-Event`       | Event type (e.g., `chat.message.completed`)               |
| `X-Webhook-Delivery-Id` | Unique delivery ID for deduplication                      |
| `Content-Type`          | `application/json`                                        |
| `User-Agent`            | `ThinnestAI-Webhooks/1.0`                                 |

## Limits

* Maximum **20 endpoints** per account
* Webhook URLs must use **HTTPS**
* Delivery timeout: **5 seconds** (configurable up to 30s)
* Maximum **3 retries** (configurable 0–5)
* Retry delays: 10s → 60s → 300s (exponential backoff)

## Quick Start

```bash theme={null}
# Create a webhook endpoint
curl -X POST https://api.thinnest.ai/webhooks/endpoints \
  -H "Authorization: Bearer thns_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/thinnestai",
    "event_types": ["chat.message.completed", "voice.call.ended"]
  }'
```

The response includes a `secret` — save it to verify incoming webhooks.

## Python SDK

```python theme={null}
from thinnestai import ThinnestAI

client = ThinnestAI(api_key="thns_sk_...")

# Create endpoint
endpoint = client.webhooks.create(
    url="https://your-app.com/webhooks",
    event_types=["chat.message.completed"],
)
print(f"Secret: {endpoint.secret}")  # Save this!

# List endpoints
for ep in client.webhooks.list():
    print(f"{ep.id}: {ep.url} ({', '.join(ep.event_types)})")

# Test it
client.webhooks.test(endpoint.id)

# View delivery history
for d in client.webhooks.deliveries(endpoint.id):
    print(f"{d.event_type}: {d.status} (attempt {d.attempts})")
```

## CLI

```bash theme={null}
# Create endpoint
thinnest webhooks create \
  --url https://your-app.com/webhooks \
  --events chat.message.completed,voice.call.ended

# List endpoints
thinnest webhooks list

# Send test event
thinnest webhooks test 1

# View deliveries
thinnest webhooks deliveries 1
```