Skip to main content
TurnCall supports Vapi-style bidirectional server hooks. The platform calls your server URL and your response can influence call behavior.

​
Setup

Bind a phone number with routing_target_type: "webhook": 
curl -X POST http://localhost:8090/v1/phone-numbers \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_number_sid": "PNxxx",
    "e164_number": "+15551234567",
    "routing_target_type": "webhook",
    "server_url": "https://your-server.com/turncall-events"
  }'
Or set server_url in the agent config for per-agent events.

​
Event Types

EventWhenResponse Controls
call-initBefore agent selectionWhich agent + variables
function-callTool executionTool result
call-endAfter call ends—
status-updateCall status changes—
transcript-updateTranscript updates—
speech-updateSpeaking events—

​
function-call

Sent when the agent calls a tool (alternative to per-tool webhook URLs).

​
Request

{
  "message": {
    "type": "function-call",
    "call": {"id": "call-uuid"},
    "functionCall": {
      "name": "lookup_customer",
      "parameters": {"phone": "+15559876543"}
    }
  }
}

​
Response

{
  "result": {"name": "John Smith", "account_id": "ACC-123"}
}

​
call-end

Sent after a call ends. Fire-and-forget (response ignored). 
{
  "message": {
    "type": "call-end",
    "call": {"id": "call-uuid"},
    "endedReason": "completed",
    "transcript": [
      {"role": "assistant", "content": "Hello!"},
      {"role": "user", "content": "I need help with billing"}
    ],
    "summary": "Customer asked about billing...",
    "durationMs": 45000
  }
}

​
Signature Verification

All server events include HMAC-SHA256 signatures: 
X-TurnCall-Signature: v1=<hex_hmac>
X-TurnCall-Timestamp: 1712345678
Verify by computing HMAC-SHA256 over "timestamp.body" using the signing secret returned when you created the phone number.