AI debug webhook | SignalWire

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.

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 payload of this webhook request is an object.

call_infoobjectRequired

Identifies the call the event came from.

session_startobjectOptional

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.

session_endobjectOptional

The AI session ended. Sent once per session.

startup_hookobjectOptional

Your startup_hook function finished, whether or not it succeeded.

hangup_hookobjectOptional

Your hangup_hook function finished, whether or not it succeeded.

speech_detectobjectOptional

Speech was recognized from the caller. Suppressed when you enable redact_prompt.

bargeobjectOptional

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.

ai_completionobjectOptional

The agent finished speaking a reply.

fillerobjectOptional

The agent played a filler phrase while it worked.

attention_timeoutobject or nullOptional

The caller went quiet for longer than attention_timeout. Sent as null on speech-to-speech sessions.

holdobjectOptional

The agent was placed on hold, or taken off it. timeout and loop come with hold only.

function_callobjectOptional

The agent called one of your functions and the call returned.

function_loopobjectOptional

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.

swaig_callobjectOptional

A completed tool call, the same entry the post-prompt callback later reports in its swaig_log.

process_actionobjectOptional

A tool returned a SWAIG action. Carries the action exactly as your endpoint returned it.

tool_distillobjectOptional

A tool result was shortened before the agent read it.

webhookobjectOptional

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.

inputobjectOptional

The body sent to the webhook, or the input an output template was expanded against.

outputobject or nullOptional

The reply the webhook produced, or the output template that matched. null when nothing matched.

matchobject or nullOptional

The entry that matched. null when none did.

error_keyslist of any or nullOptional

The error_keys declared on the webhook. null when it declares none.

errorobjectOptional

The webhook could not be evaluated.

expressionobjectOptional

The expressions entry as you wrote it. Arrives alongside input and output.

webhook_logobjectOptional

A webhook request completed, with the request and response recorded.

webhook_replyobject or nullOptional

The final reply the webhook produced, after matching. An array reply is wrapped as { "array": [...] }. null when the webhook produced no reply.

webhook_failobjectOptional

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.

step_changeobjectOptional

The agent moved to a different step.

context_changeobjectOptional

The agent moved to a different context.

context_switch_dataobjectOptional

The data a context switch was rendered against.

gather_startobjectOptional

A gather started collecting answers.

gather_questionobjectOptional

A gather asked a question.

gather_answerobjectOptional

A gather accepted an answer.

gather_rejectobjectOptional

A gather rejected an answer and will ask again.

gather_completeobjectOptional

A gather finished.

conversation_addobjectOptional

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.

llm_requestobjectOptional

The agent is about to call the model. Sent only at debug_webhook_level 2 and above.

llm_responseobjectOptional

The model answered. Sent only at debug_webhook_level 2 and above.

llm_errorobjectOptional

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.

consolidationobjectOptional

The conversation passed its token ceiling and was summarized to make room.

summarize_startobjectOptional

The post-prompt summary is about to be generated.

post_promptobjectOptional

The post-prompt report was delivered.

text_normalizeobjectOptional

Text was rewritten between spoken and written form, for recognition or speech.

voice_errorobjectOptional

The configured voice could not be used and the agent fell back to another.

warningobjectOptional

Something about the configuration is likely to cause trouble.

oart_user_transcriptobjectOptional

The caller’s speech was transcribed. Speech-to-speech sessions only.

oart_assistant_transcriptobjectOptional

The agent’s speech was transcribed. Speech-to-speech sessions only.

oart_response_doneobjectOptional

The agent finished a reply, with its timings. Speech-to-speech sessions only.

inner_dialogobjectOptional

The agent’s private reasoning, when you enable enable_inner_dialog. Speech-to-speech sessions only.

Response

200

Webhook received