Skip to main content

​
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
  • Twilio (TwiML)
  • Vonage (NCCO)
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Connect>
        <Stream url="wss://your-domain/api/v1/telephony/ws/123/456/789" />
    </Connect>
</Response>

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

  • Verify your domain/tunnel URL is publicly accessible
  • Check firewall rules allow incoming HTTPS traffic
  • Test with curl from external network
  • Check WebSocket upgrade headers are preserved
  • Verify no timeout on load balancer/proxy
  • Monitor for memory/CPU constraints
  • Verify workflow_run_id is included in URL
  • Check provider console for webhook errors
  • Review webhook retry logs