Skip to main content
Point your agent at one or more endpoints on your server and Fish Audio calls them when things happen: call.ended the moment a session reaches a terminal state, call.analyzed with the transcript once post-call analysis settles, and, on outbound phone calls, phone_call.dial_finished as soon as the dial attempt resolves. Use them to write results into your CRM, ticketing system, or data warehouse without polling the sessions API. Inbound phone calls also have an inbound call webhook that runs before the agent answers, so your server can look up the caller and hand back the values for the prompt’s {{placeholders}}.

Events

For a given session, call.ended is sent first, and every answered production call produces both events. call.ended does not carry the transcript. call.analyzed is sent after the transcript is complete, and it carries the full timeline in items. It is sent even when no analysis is configured. When analysis has nothing to work with (the caller never spoke, or analysis is disabled) or fails, call.analyzed still arrives, with analysis.status set to skipped or error and empty result sections. phone_call.dial_finished fires only for outbound calls, and it fires whether or not anyone picks up. An answered outbound call produces all three events, phone_call.dial_finished first; an outbound call that is never answered (a dial_status of busy, no_answer, or failed) produces phone_call.dial_finished and nothing else. Unanswered calls are not billed and not analyzed.
Only call.analyzed carries the transcript. To read it while the call is still running, or again later, use GET /v1/agent/sessions/{session_id}. See conversation history.

Configure the endpoint

Webhooks live in the webhooks section of your agent’s configuration. post_call is a list, so one agent can fan events out to several systems at once (the section’s other entry, conversation_init, is the inbound call webhook). Set them in the console on your agent’s Webhooks page, or via the config API:
The list is replaced as a whole on each update, so send every endpoint you want to keep. Set it to null or [] to stop deliveries. A single post_call object is still accepted and is treated as a one-element list. Secrets are write-only, so an entry sent without a secret keeps the secret already stored for that url; you can read the configuration, edit the list, and send it back without re-entering secrets.
Webhook settings are part of the agent configuration, so they follow the draft-and-publish flow: publish for changes to apply to production calls.

Payload

Every payload carries the event name, a unique event_id, and a session object with the session facts. Note the field names differ from the sessions API, which uses session_id / started_at / ended_at for the same facts. call.ended adds ended_reason and llm_endpoint_errors. call.analyzed adds the analysis entity and the transcript items. phone_call.dial_finished adds top-level dial_status and answered_by. The session object is the same on every event. The phone_call.dial_finished example shows it in full, the others are shortened.
event_id is evt_ followed by 32 hex characters. It identifies one event. Every endpoint and every retry of that event gets the same value, and it is also sent in the X-Fish-Webhook-Id header. Use it to drop duplicates. See Idempotency. items on call.analyzed is the same timeline as items in GET /v1/agent/sessions/{session_id}: messages, tool calls, tool results, and transfers, in the order they happened. See Item types for the fields. items is [] when the session’s content was already deleted by data retention, and null when it could not be read. In that case, fetch the session from the sessions API. ended_reason is the same value as session.end_reason and uses the sessions API vocabulary: user_hangup, agent_hangup, escalated, conversation_timeout, heartbeat_timeout, agent_join_timeout, internal_error, or llm_endpoint_failure. call.ended is only sent for sessions in which a participant connected, so the never-connected reasons (room_join_timeout, cancelled, dial_failed) do not appear here; query the sessions API with status=failed for those. A caller who connected and waited for an agent that never joined does produce call.ended, with session.status set to failed and ended_reason set to agent_join_timeout. In the rare case the reason is not settled yet at delivery time, both fields are null. New values may be added; treat unrecognized values as informational rather than rejecting the event. call.ended also carries llm_endpoint_errors. It lists the failures of your custom LLM endpoint during the session, in the same shape as the sessions API. It is empty on platform models. It is null in the rare case the list could not be read at delivery time. dial_status is answered, busy, no_answer, or failed. answered_by is deprecated: answering-machine detection has been removed, so it is unknown once the call is answered and null before (older events may carry human or voicemail). Both facts also appear on the session, alongside direction (inbound or outbound) and batch_call_id (reserved, always null today); these session fields are present in every webhook payload, with the dial fields null on inbound sessions. The phone_call.dial_finished snapshot is taken when the dial resolves, so on an answered call conversation_ended_at and duration_seconds are still null. The final numbers arrive with call.ended. caller_number, dialed_number and sip_call_id carry the same values as on the sessions API: the E.164 numbers of the call (person-centric on outbound calls, so caller_number is the party you dialed) and the SIP Call-ID of the call’s INVITE. All three are empty strings on web sessions, and sip_call_id is also empty on an unanswered outbound dial. caller_id_withheld is true when the carrier hid the caller’s number; caller_number is then an empty string. It is false on phone and WhatsApp sessions whose number was shown, on outbound calls, and on calls made before the field existed, and null on web and other non-call sessions. It is in every call.ended, call.analyzed and phone_call.dial_finished payload, even where the shortened examples leave it out. How to use it against your carrier’s records: Match calls with your SIP records. call_sid is the carrier’s id of the call. Today that is Twilio’s CallSid on an inbound call through a Twilio number. It is the same value the inbound call webhook request carries, so you can join that request to the session. It is an empty string on web sessions, outbound calls, and calls through your own SIP trunk. end_user_id and metadata are echoed exactly as you set them when creating the session. Use them to correlate the event with records in your own system. branch_id is an internal configuration-lineage identifier and is safe to ignore. What lands in summary, data, and criteria_results is defined by your analysis configuration. The example shows a completed analysis. analysis.status can also be skipped (nothing to analyze: the caller never spoke, or analysis is disabled) or error (the run failed, with the cause in analysis.error); both arrive with summary: null and empty data / criteria_results. Check the status before reading results.

Verify the signature

When an entry has a secret, every request to that endpoint carries a signature header with the send time and an HMAC-SHA256 of {timestamp}.{raw_body}, keyed with that entry’s own secret:
Every post-call request also carries the event’s X-Fish-Webhook-Id header, the same value as event_id in the body. The body is what is signed, so trust event_id in a verified body over the header. t is the Unix time (seconds) the request was sent. Each attempt is signed again with its own timestamp over the same body. v1 is the hex HMAC. Verify in three steps:
  1. Parse t and v1 from the header.
  2. Recompute HMAC-SHA256 over the string {t}. followed by the raw request body bytes (before any JSON parsing or re-serialization) and compare against v1 in constant time.
  3. Reject requests whose t is more than 5 minutes from your clock. Because the timestamp is inside the MAC, a replayed capture can’t be refreshed.
Reject requests with a missing or invalid signature. Without verification, anyone who discovers your endpoint URL can forge call results.
Future scheme revisions would ship under a new element (v2=…) alongside v1. Parse the elements you know and ignore the rest, as the snippets above do.

Delivery semantics

Endpoints are delivered in parallel and independently: each gets its own attempts, its own retry budget, and its own signature keyed with its own secret. An endpoint that is down and exhausts all seven attempts has no effect on the others. Respond with a 2xx status within the timeout. Acknowledge first and process asynchronously. Slow handlers burn their own retry budget. What happens to an attempt that does not get a 2xx: Deliveries can arrive more than once, and a retry can arrive after a later event for the same session. Don’t assume call.analyzed arrives after call.ended.
Preview calls made from the Builder never trigger webhooks. To test end to end, run a real session against your published agent.

Idempotency

At-least-once delivery means the same event can arrive more than once. Retries of one event carry an identical body, so store each event_id you process and drop any event whose event_id you have already seen. A skipped or failed analysis can be re-run from the console. The recovered result arrives as a new call.analyzed with a new event_id and a newer analysis.finished_at. It supersedes the earlier one, so keep the call.analyzed with the latest finished_at for each session.id.

Forward compatibility

Payloads change additively. This applies to every webhook on this page, including the inbound call webhook request.
  • New fields can appear at any time, at the top level and inside session, analysis and call. They come without a new event name.
  • Published fields never change name, type or meaning, and are never removed.
  • Enum fields such as status and ended_reason can gain new values.
Parse payloads without rejecting unknown fields. A receiver that validates against a strict schema breaks when a field is added. Treat an enum value you don’t recognize as a generic case instead of failing.

Inbound call webhook

webhooks.conversation_init is a single endpoint called while an inbound phone call is being set up, before the agent answers. It receives the caller’s number and returns dynamic_variables that fill the {{placeholders}} in the agent’s published prompt and first message, so the agent can greet a known customer by name or pick up an open order. In the console it is the Inbound call webhook on the agent’s Webhooks page. Only inbound phone calls use it. Web sessions and outbound calls carry their dynamic variables on the request that creates them, and preview calls never call it.
Configure
Send "conversation_init": null to remove the endpoint. Like the rest of the configuration, the change applies to phone calls after the next publish.

Request

The platform sends one POST with a JSON body:
call.inbound
caller_number and dialed_number are E.164. caller_number is an empty string when the carrier withholds the caller’s number, and caller_id_withheld is a boolean that says so: true when the number is withheld, false otherwise. Withheld means the carrier sent no digits (anonymous, restricted, an empty value) or one of the placeholder numbers Twilio uses when it has none, so a placeholder never reaches you as a number. When it is true, skip the lookup by number in your endpoint; the agent can ask who is calling instead, see Withheld caller ID. call_sid is empty when the call did not come through a Twilio number. To match this request with the call, keep call_sid. Once the call is connected, GET /v1/agent/sessions?call_sid=… returns its session, and post-call webhooks carry the same value. This works only when call_sid is not empty, that is for calls through a Twilio number. During the call, webhook tools can send the session id with {{system.session_id}}. New fields can be added to this request, see Forward compatibility.

Response

Respond with a 2xx status and a JSON object whose dynamic_variables follow the same rules as on session creation: names match [A-Za-z][A-Za-z0-9_]*, values are strings (up to 100,000 characters), numbers, or booleans, and at most 500 entries totaling 1 MiB are read.
Response
An entry that breaks a rule is dropped on its own; the call still connects with the rest. Other fields in the response are ignored, so the contract can grow without breaking deployed endpoints. A placeholder that receives no value takes the agent’s configured default value, and follows the agent’s If a variable has no value setting (on_missing in the API) when there is none.
A variable in a transfer destination’s phone number is the exception: that setting does not apply there, and only that destination is skipped for the call.
System prompt

Failure behavior

The endpoint can personalize a call but never block one. The caller is waiting while the request runs, so keep the handler fast and the timeout short. Whenever the call connects without your variables, every placeholder falls back to its configured default value, so give each one a default that reads well on its own.

Auto-ticket unresolved calls

call.analyzed closes the loop on conversations the agent couldn’t: judge every call with a success criterion, and open a ticket in your helpdesk whenever the verdict isn’t success. First give the agent’s analysis configuration a criterion that captures resolution:
analysis.criteria
Then add your endpoint to webhooks.post_call (see Configure the endpoint) and act on the verdict:
verifyWebhook is the function from Verify the signature; openTicket stands in for your helpdesk’s API. Escalating on anything but success includes unknown verdicts: the model couldn’t judge the call, which usually deserves human eyes too. Tighten the check to failure only if unknowns prove noisy. Edges worth handling:
  • Calls with nothing to analyze arrive with analysis.status: "skipped". The handler above tickets them as unjudged, so every call reaches the helpdesk without also watching call.ended. Drop that branch if silent calls don’t belong in your queue.
  • To include the transcript in the ticket, read it from payload.items. When items is null, fetch GET /v1/agent/sessions/{session_id} from your handler instead. See conversation history.
  • Set end_user_id and metadata when creating sessions so tickets attach to the right customer record without a lookup.
Post-call ticketing is silent: the caller has already hung up. When the caller should leave the call holding a ticket number, have the agent open it mid-call with a webhook tool, and keep this recipe as the safety net behind it.

Going further

Post-call analysis

Define the summary, data fields, and criteria that call.analyzed delivers.

Conversation history

Fetch the transcript, tool timeline, and recordings by session_id.

Versions & publishing

How configuration changes (including webhooks) go live.

Agent configuration

The full config schema behind PATCH /v1/agent/agents/{agent_id}/config.