Webhooks

Webhook Events

Reference for every event Katexs emits, when it fires, and what the payload contains. All events share a common envelope.

Envelope

json

{
  "id": "evt_01J8XQ",
  "type": "call.ended",
  "created_at": "2026-08-02T15:07:41Z",
  "workspace_id": "ws_42",
  "agent_id": "agt_123",
  "call_id": "cl_889",
  "sequence": 14,
  "data": { }
}

Call lifecycle events

Event	Fires when	Key data fields
call.queued	An outbound call is accepted.	to, from, scheduled_at
call.ringing	The carrier begins dialing.	to, from
call.started	The call is answered.	direction, caller_id, variables
call.ended	The call terminates for any reason.	ended_reason, duration_sec, cost, recording_url
call.transferred	The caller is bridged elsewhere.	mode, destination, summary

Conversation events

Event	Fires when	Key data fields
transcript.partial	Interim speech is recognized.	role, text, is_final: false
transcript.final	An utterance completes.	role, text, start_ms, end_ms, confidence
speech.interrupted	The caller barges in on the agent.	at_ms, discarded_text
voicemail.detected	An answering machine is detected.	confidence, action_taken

transcript.partial is high volume — one event every few hundred milliseconds. Subscribe to it only if you are rendering a live transcript.

Tool events

Event	Fires when	Key data fields
tool.called	The agent invokes a tool.	tool, arguments, invocation_id
tool.completed	The tool returns successfully.	invocation_id, result, duration_ms
tool.failed	The tool errors or times out.	invocation_id, error, status_code

Example: tool.called

json

{
  "type": "tool.called",
  "call_id": "cl_889",
  "data": {
    "tool": "book_appointment",
    "invocation_id": "inv_7",
    "arguments": {
      "date": "2026-08-05",
      "time": "10:00",
      "service": "cleaning"
    }
  }
}

Post-call events

Event	Fires when	Key data fields
recording.ready	Audio is processed and stored.	recording_url, duration_sec, expires_at
insights.ready	Sentiment, keywords, and score are computed.	sentiment, keywords, score, summary
campaign.completed	Every contact in a campaign is dialed.	campaign_id, totals, outcomes

Responding to events

Most events are informational — return 200 and move on. Two events accept a response body that changes behavior: call.inbound (see Spam Rejection) and tool.called when the tool is configured as server-resolved.

json

{
  "result": { "available": ["10:00", "11:30", "14:15"] }
}