Webhooks and Callbacks

Overview#

Lemu 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

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

Lemu 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

Troubleshooting#