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

# Webhooks

> Subscribe to real-time call events and notifications

<Note>
  Subscribe to webhook events at [app.sawt.sa/webhooks/subscriptions](https://app.sawt.sa/webhooks/subscriptions) to receive real-time notifications about your calls.
</Note>

## Overview

Webhooks allow you to receive real-time notifications about call events, enabling you to build responsive applications that react to call status changes, analysis results, and other important events.

## Event Types

### Call Lifecycle Events

<Accordion title="1. Call Initializing">
  **Routing Key:** `call.initializing`

  **Description:** Triggered when a call request is received and initialization begins.

  ```json theme={null}
  {
    "call_id": "call_123",
    "agent_id": "agent_456",
    "to_number": "966500000000",
    "from_number": "966511111111",
    "call_status": "RECEIVED_REQUEST_TO_AGENT",
    "direction": "INBOUND"
  }
  ```
</Accordion>

<Accordion title="2. Call Started">
  **Routing Key:** `call.started`

  **Description:** Emitted once the agent joins the room and the call is active.

  ```json theme={null}
  {
    "call_id": "call_123",
    "agent_id": "agent_456",
    "to_number": "966500000000",
    "from_number": "966511111111",
    "call_status": "IN_CALL",
    "direction": "OUTBOUND",
    "agent_version": "v2"
  }
  ```
</Accordion>

<Accordion title="3. Call Status Updated">
  **Routing Key:** `call.updated`

  **Description:** Published whenever the call status transitions (e.g. ringing, in-call).

  ```json theme={null}
  {
    "call_id": "call_123",
    "agent_id": "agent_456",
    "to_number": "966500000000",
    "from_number": "966511111111",
    "call_status": "IN_CALL",
    "previous_call_status": "CALLING",
    "direction": "OUTBOUND",
    "agent_version": "v2",
    "call_start_timestamp": "2025-05-01T10:00:00.000Z",
    "call_end_timestamp": null,
    "duration_s": 42,
    "call_cost": 1.15
  }
  ```
</Accordion>

<Accordion title="4. Call Ended">
  **Routing Key:** `call.ended`

  **Description:** Sent after post-call cleanup completes for finished calls.

  ```json theme={null}
  {
    "call_id": "call_123",
    "agent_id": "agent_456",
    "to_number": "966500000000",
    "from_number": "966511111111",
    "call_status": "FINISHED",
    "previous_call_status": "IN_CALL",
    "direction": "INBOUND",
    "agent_version": "v3",
    "call_start_timestamp": "2025-05-01T10:00:00.000Z",
    "call_end_timestamp": "2025-05-01T10:05:15.000Z",
    "duration_s": 315,
    "call_cost": 8.75,
    "transcript_object": [
      {
        "role": "AGENT",
        "text": "Hello, thanks for calling."
      },
      {
        "role": "CUSTOMER", 
        "text": "Hi, I need help with my order."
      }
    ],
    "previously_transferred_to_human": false
  }
  ```
</Accordion>

### Tool Failure Events

<Accordion title="5. Knowledge Base Tool Failed">
  **Routing Key:** `tool.knowledge_base.failed`

  **Description:** Emitted when the knowledge base search tool encounters an error.

  <Info>
    This helps you identify missing information in your knowledge base and improve your agent's responses.
  </Info>

  ```json theme={null}
  {
    "call_id": "call_123",
    "agent_id": "agent_456",
    "tool_name": "knowledge_base",
    "error_message": "No articles matched query",
    "error_type": "NO_RESULTS",
    "timestamp": "2025-05-01T10:02:05.000Z"
  }
  ```
</Accordion>

<Accordion title="6. Function Tool Failed">
  **Routing Key:** `tool.function.failed`

  **Description:** Triggered whenever a custom function tool throws an error.

  ```json theme={null}
  {
    "call_id": "call_123",
    "agent_id": "agent_456",
    "tool_name": "send_sms",
    "error_message": "Internal API timeout",
    "timestamp": "2025-05-01T10:03:44.000Z"
  }
  ```
</Accordion>

### Post-Call Events

<Accordion title="7. Call Analyzed">
  **Routing Key:** `call.analyzed`

  **Description:** Emitted after post-call analysis completes with summary, sentiment, evaluation, and structured data.

  <Info>
    This enables post-call automation based on AI analysis results.
  </Info>

  ```json theme={null}
  {
    "call_id": "call_123",
    "call_summary": "Customer called to inquire about their recent order status. Agent provided tracking information and resolved the issue successfully.",
    "user_sentiment": "POSITIVE",
    "call_evaluation": true,
    "structured_data_result": {
      "testData": "1234"
    }
  }
  ```
</Accordion>

## Webhook Configuration

### Setting Up Webhooks

1. **Navigate to Subscriptions**\
   Visit [app.sawt.sa/webhooks/subscriptions](https://app.sawt.sa/webhooks/subscriptions)

2. **Create Endpoint**\
   Add your webhook URL that will receive the events

3. **Select Events**\
   Choose which event types you want to subscribe to

4. **Configure Settings**\
   Set up authentication preferences

5. **Test Delivery**\
   Use the test functionality to verify your endpoint works