Webhooks and Callbacks

Overview#

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

    [
      {
        "action": "connect",
        "endpoint": [{
          "type": "websocket",
          "uri": "wss://your-domain/api/v1/telephony/ws/123/456/789",
          "content-type": "audio/l16;rate=16000"
        }]
      }
    ]

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#

Paladin AI automatically:

1. Constructs webhook URLs based on your Paladin workspace
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

1. Processes status updates to track call lifecycle
2. Manages WebSocket connections for audio streaming
3. Handles provider-specific audio formats and protocols

Troubleshooting#