Skip to navigation

Call events to your server

Studio posts what happens during a call to your server as it happens, and your reply can steer the agent.

An agent can post chosen events to your server while each call runs: the call starting, what the caller says, what the agent replies, a tool’s result, situations starting and ending, the call ending. Your server can answer any event with actions: start a situation, add context, change the agent’s instructions, make it speak, transfer or end the call.

Studio never waits for your answer. The call carries on, and your reply’s actions are applied when it arrives.

Call events need an agent where jambonz runs speech-to-text, the language model and text-to-speech (a cascaded voice pipeline). An agent with any other engine can’t publish with call events chosen.

Turning them on

In the agent builder, open Situations. Under Call events to your server:

  1. URL: your server’s endpoint, a public https URL.
  2. Events: the events to post. Nothing is posted until you choose at least one.

An agent with events chosen and no URL won’t publish. Test calls from the builder post events too.

The events

EventBuilder labelPosted whendata
call_startCall startsthe call reaches the agentdirection (inbound or outbound), from, to, test (true for a test call)
user_transcriptCaller speaksthe caller finishes a turntranscript
llm_responseAgent repliesthe agent’s reply for a turn is completeresponse
user_interruptionCaller interruptsthe caller talks over the agent and cuts it offnone
tool_resultTool returnsone of the agent’s HTTP or MCP tools returnsname, ok (false for an error result), result: what the model got
situation_enteredSituation startsa situation startsname, by (model, tool, webhook or push), tool, active
situation_resolvedSituation resolvesa situation is resolvedthe same fields as situation_entered
call_endCall endsthe call endsstatus, and sip_status when there is one

user_transcript and llm_response post once per turn and send the conversation’s text to your server. Choose them only if your server needs it.

The request

Each event is a POST with a JSON body:

{
"event": "user_transcript",
"call_sid": "b2a9f6c1-4d0e-4a55-9a5e-2f1c0e7d8a31",
"agent_id": "7f3c2a9e-1b4d-4c8e-9f2a-6d5b3e1c0a47",
"seq": 4,
"turn": 2,
"ts": "2026-11-12T14:02:11.482Z",
"data": { "transcript": "Has my payment gone through yet?" }
}
FieldWhat it is
eventthe event, from the table above
call_sidthe jambonz call id. Use it to push actions into this call later
agent_idthe Studio agent’s id
seqthe event’s number in this call, from 1. Deliveries can arrive out of order: sort by seq
turnhow many times the caller has spoken so far. It starts again from 0 if the call’s connection to Studio is re-established
tswhen Studio sent the event
datathe event’s details

Headers:

HeaderWhat it is
x-studio-eventthe event, as in the body
x-studio-signaturethe signature: see below

Verifying the signature

Events are signed exactly as the result webhook is, with the agent’s same signing secret (starting whsec_):

x-studio-signature: t=<unix seconds>,v1=<hex>
v1 = hex(HMAC-SHA256(signing_secret, t + "." + raw_body))

Verify the raw body exactly as received, and reject a request whose t is more than a few minutes from your clock. The result webhook page has the code, and shows where to reveal and rotate the secret. Studio creates the secret when you publish the agent, or start a test call, with events chosen.

Your reply

Answer within 3 seconds with a 2xx status. The body can be:

  • empty: nothing happens;
  • a JSON object with actions: Studio applies them to the call;
{ "actions": { "inject_context": "Their payment of $240.00 arrived at 14:02.", "generate_reply": true } }
  • any other JSON: ignored.

Replies are applied in the order they arrive. The actions page lists every action, and the per-call limits on actions from replies.

Keep your handler fast. The agent doesn’t wait for you, so a slow reply lands later in the conversation than the event it answers: by the time a reply to Caller speaks arrives, the agent may already be answering the caller.

Delivery

  • No retries. An event is posted once. A retried event would arrive too late to be useful.
  • 3-second timeout. No answer within 3 seconds is a failed delivery.
  • No redirects. A 3xx answer is a failed delivery.
  • At most 8 deliveries at a time per call. An event over that is not sent, and is recorded as failed.
  • Replies up to 64 KB.
  • Paused after 3 failures in a row. The call stops posting events for the rest of the call. A successful delivery resets the count. The next call starts again.

Studio doesn’t post to private network addresses, or to names that resolve to them.

When a delivery fails

Each failure is on the call’s timeline in Calls as Event webhook failed, with the event and the reason:

ReasonMeans
no answer in 3 syour server didn’t answer in time
HTTP <status>your server answered with a status other than 2xx
unreachablethe connection failed
blocked: private hostthe URL resolves to a private address
reply is not JSONa 2xx answer with a body that isn’t JSON
reply too large or cut offa reply over 64 KB, or one that stopped part way
too many deliveries in flight8 deliveries for this call were still waiting for your server
the agent has no signing secretpublish the agent again to create one

When the call stops posting, the timeline shows Event webhook paused.

Example

A billing agent tells the caller when their payment lands, using knowledge the model can’t have:

  1. Choose Caller speaks and Call ends.

  2. On user_transcript, look the caller up by call_sid. If they ask about a payment and it has arrived, reply:

    {
    "actions": {
    "inject_context": "Payment of $240.00 received at 14:02, reference PAY-8812.",
    "generate_reply": "Confirm the payment and read the reference."
    }
    }
  3. On call_end, stop watching for the call’s payments.

If the payment arrives later in the call, push the same actions when it does.

Next