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

# Webhooks and Callbacks

> How Asisso handles telephony webhooks and audio streaming

## Overview

Asisso uses webhooks to communicate with telephony providers for call events and audio streaming. Webhooks are automatically configured when you initiate calls.

## Webhook Types

### 1. Initial Call Webhook

When a call is initiated, the telephony provider requests instructions.

**Endpoint**: `/api/v1/telephony/webhook/{workflow_id}/{user_id}/{workflow_run_id}`

**Purpose**: Returns provider-specific instructions

<Tabs>
  <Tab title="Twilio (TwiML)">
    ```xml theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <Response>
        <Connect>
            <Stream url="wss://your-domain/api/v1/telephony/ws/123/456/789" />
        </Connect>
    </Response>
    ```
  </Tab>

  <Tab title="Vonage (NCCO)">
    ```json theme={null}
    [
      {
        "action": "connect",
        "endpoint": [{
          "type": "websocket",
          "uri": "wss://your-domain/api/v1/telephony/ws/123/456/789",
          "content-type": "audio/l16;rate=16000"
        }]
      }
    ]
    ```
  </Tab>
</Tabs>

### 2. Status Callback

Receives call lifecycle events.

**Endpoint**: `/api/v1/telephony/status-callback/{workflow_run_id}`

**Events Tracked**:

* `initiated` - Call request received
* `ringing` - Call is ringing
* `answered` - Call was answered
* `completed` - Call ended normally
* `busy` - Line was busy
* `no-answer` - Call not answered
* `failed` - Call failed

### 3. WebSocket Audio Stream

Real-time audio streaming for voice interaction.

**Endpoint**: `/api/v1/telephony/ws/{workflow_id}/{user_id}/{workflow_run_id}`

**Audio Formats**:

* **Twilio**: 8kHz μ-law (MULAW), Base64-encoded in JSON messages
* **Vonage**: 16kHz Linear PCM, Binary frames

## How It Works

Asisso automatically:

1. Constructs webhook URLs based on your deployment
2. Passes them to the telephony provider when initiating calls
3. Verifies webhook signatures for security:
   * **Twilio**: HMAC-SHA1 signature validation
   * **Vonage**: JWT token verification
4. Processes status updates to track call lifecycle
5. Manages WebSocket connections for audio streaming
6. Handles provider-specific audio formats and protocols

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook URL not accessible">
    * Verify your domain/tunnel URL is publicly accessible
    * Check firewall rules allow incoming HTTPS traffic
    * Test with `curl` from external network
  </Accordion>

  <Accordion title="WebSocket connection dropping">
    * Check WebSocket upgrade headers are preserved
    * Verify no timeout on load balancer/proxy
    * Monitor for memory/CPU constraints
  </Accordion>

  <Accordion title="Status callbacks not received">
    * Verify workflow\_run\_id is included in URL
    * Check provider console for webhook errors
    * Review webhook retry logs
  </Accordion>
</AccordionGroup>