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

Register an endpoint with a URL and event types
Receive a signing secret (shown once — save it)
Events fire as your agents operate
ThinnestAI POSTs signed JSON to your URL
Verify the signature to confirm authenticity
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:

{
  "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

# 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

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

# 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

On this page