---
title: "Webhooks and Callbacks"
description: "How Dograh AI handles telephony webhooks and audio streaming"
---

## Overview

Dograh AI 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
    <?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
    [
      {
        "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

Dograh AI 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

## Local Development

For local development, use the built-in Cloudflare tunnel:

```yaml
# docker-compose.yml includes:
cloudflared:
  image: cloudflare/cloudflared:latest
  command: tunnel --no-autoupdate --url http://api:8000
```

The tunnel URL is automatically detected and used for webhooks.

## 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>