Skip to main content

​
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

EventDescription
agent.createdNew agent created
agent.updatedAgent configuration changed
agent.deletedAgent deleted
chat.message.completedAgent finished responding to a chat message
chat.session.endedChat session ended
voice.call.startedVoice call connected
voice.call.endedVoice call ended
campaign.step.completedCampaign step executed
campaign.completedCampaign finished
webhook.testTest 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:
HeaderDescription
X-Webhook-Signaturesha256=<hmac_hex> — HMAC-SHA256 of {timestamp}.{body}
X-Webhook-TimestampUnix timestamp (seconds)
X-Webhook-EventEvent type (e.g., chat.message.completed)
X-Webhook-Delivery-IdUnique delivery ID for deduplication
Content-Typeapplication/json
User-AgentThinnestAI-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