AI debug webhook
A diagnostic feed for a call that is still in progress. Set debug_webhook_url on your agent and
every step it takes is posted to that URL as it happens: speech recognized, model called, tool
invoked, context switched, error hit. Use it to work out why a call went the way it did — which
tool the agent reached for, what came back, where a turn went wrong — or to react while the call is
still live, such as paging a supervisor.
Each request carries call_info plus one or more event properties, where the property name is the
event. One moment can produce several: evaluating a data_map webhook sends webhook, input,
output, error_keys, and match together. Handle the properties you recognize and ignore the
rest, since the set grows over time.
Setting the URL is what enables the feed. debug_webhook_level only widens it: at 2 it also
carries conversation_add, llm_request, and llm_response, which fire on every turn and every
model call.
Payload
The AI session started. Sent once per session. The fields differ by session type: a standard
session reports the voice it will use, while a speech-to-speech session reports mode as oart
along with its audio settings and reports no voice at all. Every field is optional, so read
mode to tell which kind of session you have.
Your startup_hook function finished, whether or not it succeeded.
Your hangup_hook function finished, whether or not it succeeded.
Speech was recognized from the caller. Suppressed when you enable redact_prompt.
The caller interrupted the agent. The fields differ by session type: a standard session reports
barge_type, barge_elapsed_ms, and interrupt_count, while a speech-to-speech session reports
audio_played_ms and barge_count.
The caller went quiet for longer than attention_timeout. Sent as null on speech-to-speech sessions.
The agent was placed on hold, or taken off it. timeout and loop come with hold only.
The agent called the same function repeatedly and was stopped. consecutive means it was called
several times in a row; repeated means it was called with the same arguments each time.
A completed tool call, the same entry the post-prompt callback later reports in its swaig_log.
The webhook definition as you wrote it. Arrives alongside input, and alongside output and
match when the call produced a reply, or error when the definition was unusable.
The reply the webhook produced, or the output template that matched. null when nothing matched.
The entry that matched. null when none did.
The error_keys declared on the webhook. null when it declares none.
The expressions entry as you wrote it. Arrives alongside input and output.
The final reply the webhook produced, after matching. An array reply is wrapped as
{ "array": [...] }. null when the webhook produced no reply.
A tool’s webhook could not be reached or did not answer usefully, after every retry. Sent whenever a tool call fails, so you can alert on tools breaking mid-call.
A gather started collecting answers.
A gather asked a question.
A gather accepted an answer.
A gather rejected an answer and will ask again.
A gather finished.
A message was added to the conversation, one per turn. Sent only at debug_webhook_level 2 and
above. This is the same message that later appears in the post-prompt callback’s call_log.
The agent is about to call the model. Sent only at debug_webhook_level 2 and above.
The model answered. Sent only at debug_webhook_level 2 and above.
A model call failed or had to be retried. Read event for which: token_exhaustion and
llm_fatal end the session, llm_max_retries gives up after repeated failures, and
llm_retry, reasoning_only_retry, empty_response_nudge_retry, and
empty_response_effort_bump_retry recover silently.
The post-prompt summary is about to be generated.
The post-prompt report was delivered.
The caller’s speech was transcribed. Speech-to-speech sessions only.
The agent’s speech was transcribed. Speech-to-speech sessions only.
The agent finished a reply, with its timings. Speech-to-speech sessions only.
The agent’s private reasoning, when you enable enable_inner_dialog.
Speech-to-speech sessions only.