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

# Webhook Events

> Complete reference of all webhook event types

# Webhook Events

This page documents all webhook events sent by Kallglot.

## Session Events

### session.created

Sent when a new session is created.

```json theme={null}
{
  "id": "evt_01HXYZ123456789",
  "type": "session.created",
  "created_at": "2026-03-26T11:00:00Z",
  "data": {
    "id": "sess_01HXYZ123456789",
    "object": "session",
    "status": "created",
    "mode": "bidirectional_translation",
    "source_language": "de",
    "target_language": "en",
    "metadata": {
      "customer_id": "cust_123"
    },
    "created_at": "2026-03-26T11:00:00Z"
  }
}
```

### session.started

Sent when a session becomes active (first audio received).

```json theme={null}
{
  "id": "evt_01HXYZ123456790",
  "type": "session.started",
  "created_at": "2026-03-26T11:00:15Z",
  "data": {
    "id": "sess_01HXYZ123456789",
    "object": "session",
    "status": "active",
    "mode": "bidirectional_translation",
    "source_language": "de",
    "target_language": "en",
    "started_at": "2026-03-26T11:00:15Z"
  }
}
```

### session.ended

Sent when a session ends.

```json theme={null}
{
  "id": "evt_01HXYZ123456791",
  "type": "session.ended",
  "created_at": "2026-03-26T11:04:20Z",
  "data": {
    "id": "sess_01HXYZ123456789",
    "object": "session",
    "status": "ended",
    "mode": "bidirectional_translation",
    "duration": 245.3,
    "end_reason": "completed",
    "recording": {
      "id": "rec_01HABC987654321",
      "duration": 245.3
    },
    "transcript": {
      "available": true,
      "word_count": 512
    },
    "started_at": "2026-03-26T11:00:15Z",
    "ended_at": "2026-03-26T11:04:20Z"
  }
}
```

### session.provider.connected

Sent when a telephony provider call connects.

<Note>
  The **`data.provider`** object in webhooks describes the telephony leg. **`POST /v1/sessions`** does **not** accept this nested object—use **`routing`** for session creation.
</Note>

```json theme={null}
{
  "id": "evt_01HXYZ123456792",
  "type": "session.provider.connected",
  "created_at": "2026-03-26T11:00:12Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "provider": {
      "type": "twilio",
      "call_sid": "CA1234567890abcdef",
      "status": "connected",
      "from": "+4915123456789",
      "to": "+14155551234"
    }
  }
}
```

### session.provider.disconnected

Sent when a telephony provider call disconnects.

```json theme={null}
{
  "id": "evt_01HXYZ123456793",
  "type": "session.provider.disconnected",
  "created_at": "2026-03-26T11:04:18Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "provider": {
      "type": "twilio",
      "call_sid": "CA1234567890abcdef",
      "status": "disconnected",
      "disconnect_reason": "customer_hangup",
      "duration": 245
    }
  }
}
```

## Transcript Events

### transcript.ready

Sent when the full transcript is available after a session ends.

```json theme={null}
{
  "id": "evt_01HXYZ123456794",
  "type": "transcript.ready",
  "created_at": "2026-03-26T11:04:30Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "word_count": 512,
    "segment_count": 45,
    "duration": 245.3,
    "languages": ["de", "en"]
  }
}
```

### transcript.segment

Sent in real-time for each transcript segment. Only delivered if you subscribe to real-time events.

```json theme={null}
{
  "id": "evt_01HXYZ123456795",
  "type": "transcript.segment",
  "created_at": "2026-03-26T11:02:15Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "segment": {
      "id": "seg_042",
      "speaker": "customer",
      "language": "de",
      "text": "Wann wird meine Bestellung geliefert?",
      "translation": "When will my order be delivered?",
      "start_time": 125.3,
      "end_time": 128.1,
      "is_final": true
    }
  }
}
```

## Recording Events

### recording.ready

Sent when a recording is processed and available for download.

```json theme={null}
{
  "id": "evt_01HXYZ123456796",
  "type": "recording.ready",
  "created_at": "2026-03-26T11:05:00Z",
  "data": {
    "id": "rec_01HABC987654321",
    "object": "recording",
    "session_id": "sess_01HXYZ123456789",
    "channel": "mixed",
    "duration": 245.3,
    "format": "mp3",
    "size": 2943600,
    "download_url": "/v1/recordings/rec_01HABC987654321/audio"
  }
}
```

### recording.failed

Sent when recording generation fails.

```json theme={null}
{
  "id": "evt_01HXYZ123456797",
  "type": "recording.failed",
  "created_at": "2026-03-26T11:05:00Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "error": {
      "code": "recording_generation_failed",
      "message": "Failed to generate recording due to audio processing error"
    }
  }
}
```

## Analysis Events

### analysis.completed

Sent when session analysis is complete.

```json theme={null}
{
  "id": "evt_01HXYZ123456798",
  "type": "analysis.completed",
  "created_at": "2026-03-26T11:10:30Z",
  "data": {
    "id": "anl_01HDEF456789012",
    "object": "analysis",
    "session_id": "sess_01HXYZ123456789",
    "status": "completed",
    "results": {
      "sentiment": {
        "overall": 0.72,
        "label": "positive"
      },
      "summary": {
        "brief": "Customer inquired about order status. Agent confirmed delivery date."
      },
      "action_items": [
        {
          "description": "Send tracking number to customer",
          "assignee": "agent",
          "priority": "high"
        }
      ],
      "quality": {
        "score": 85
      }
    }
  }
}
```

### analysis.failed

Sent when analysis fails.

```json theme={null}
{
  "id": "evt_01HXYZ123456799",
  "type": "analysis.failed",
  "created_at": "2026-03-26T11:10:30Z",
  "data": {
    "id": "anl_01HDEF456789012",
    "session_id": "sess_01HXYZ123456789",
    "error": {
      "code": "analysis_failed",
      "message": "Unable to analyze transcript due to insufficient content"
    }
  }
}
```

## AI Agent Events

### ai\_agent.tool\_called

Sent when an AI agent invokes a tool/function.

```json theme={null}
{
  "id": "evt_01HXYZ123456800",
  "type": "ai_agent.tool_called",
  "created_at": "2026-03-26T11:02:30Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "tool": {
      "name": "lookup_order",
      "arguments": {
        "order_number": "12345"
      },
      "call_id": "call_abc123"
    }
  }
}
```

### ai\_agent.escalation\_requested

Sent when an AI agent requests human escalation.

```json theme={null}
{
  "id": "evt_01HXYZ123456801",
  "type": "ai_agent.escalation_requested",
  "created_at": "2026-03-26T11:03:00Z",
  "data": {
    "session_id": "sess_01HXYZ123456789",
    "reason": "Customer requested to speak with a human",
    "context": {
      "summary": "Customer has billing dispute that requires manager approval",
      "sentiment": "frustrated"
    }
  }
}
```

## Subscribing to Events

In the Developer Portal, you can select which events to receive for each webhook endpoint:

| Category    | Events                                                        |
| ----------- | ------------------------------------------------------------- |
| Sessions    | `session.created`, `session.started`, `session.ended`         |
| Provider    | `session.provider.connected`, `session.provider.disconnected` |
| Transcripts | `transcript.ready`, `transcript.segment`                      |
| Recordings  | `recording.ready`, `recording.failed`                         |
| Analysis    | `analysis.completed`, `analysis.failed`                       |
| AI Agent    | `ai_agent.tool_called`, `ai_agent.escalation_requested`       |

<Note>
  Real-time events like `transcript.segment` may generate high volumes. Consider using WebSocket streaming instead for real-time data.
</Note>