Webhooks

/api/v1/webhooks/* is an inbound endpoint on TelAPI. It is not a way for Delphi to notify your systems — it's the opposite direction. When an LLM provider or a tool runs async (the platform asked it to do work and didn't wait for the answer), the external system posts the result back here, and TelAPI routes it into the still-active conversation.

This is a separate surface from the WebRTC API:

• Uses its own per-callback auth, not the tenant's API key.
• Not controlled by API-key scopes (CREATE_CALL_TOKEN, READ_TEAM_APPS, etc.).
• Not gated by the webrtc feature flag — async flows run regardless of WebRTC.

If you were looking for "the platform calling my system when a call ends", use TelWeb conversation history today. This endpoint is specifically for async providers and managed integrations returning work back into an active conversation.

When you'll use this endpoint

You will use /api/v1/webhooks/* if:

• You operate an LLM or tool provider that Delphi flows call out to, and your provider works asynchronously (you accept the request, return 202, then post the real answer back later).
• You're building a custom tool integration where the tool may take longer than the flow's inline budget and you want the conversation to continue while the tool works.

You will not use this endpoint to:

• Receive conversation-completed events. (Not exposed on this inbound callback surface.)
• Authenticate as a tenant. (Use a WebRTC API key.)
• Configure flows or providers. (Use TelWeb.)

Flow shape

The key idea: the original request from Delphi to your system includes the callback URL and the token you'll need to POST back. Treat them as one-shot credentials scoped to that one piece of work.

Auth model

Inbound webhook routes are not authenticated with the tenant's Authorization: Bearer <api-key> model. Each integration defines how the async caller proves it is allowed to post back — always follow the exact header, query, and body contract from the outbound request Delphi (or the carrier) sent you.

Typical properties:

• A short-lived credential scoped to one work item or conversation channel.
• One-shot semantics where replay or reuse after completion is rejected.
• If the conversation has already ended or the credential has been consumed, the platform rejects the callback.

TOBi (/api/v1/webhooks/tobi/:channelId)

POST /api/v1/webhooks/tobi/:channelId receives asynchronous TOBi responses. The provider supplies the per-conversation callback token as a header named token, with the raw token string as the header value (not Bearer …, not a query parameter). TelAPI validates only this header for TOBi callback authentication.

Trace correlation may still be passed as query parameters (traceId, parentSpanId, callId).

curl -X POST "https://${DOMAIN_API}/api/v1/webhooks/tobi/<channelId>?traceId=<traceId>&parentSpanId=<spanId>&callId=<callId>" \
  -H "token: <callback-token>" \
  -H "Content-Type: application/json" \
  -d '{"conversation":{"identifier":{"id":"<channelId>"}},"messages":{"message":[]}}'

For other async LLM or tool integrations, the outbound request names the header or transport to use — do not assume it matches TOBi or the illustrative X-Delphi-Callback-Token pattern in Examples.

Do not log callback tokens

Treat the callback credential like a one-shot secret. Don't write it to logs, don't store it longer than needed, don't share it across work items.

What to POST back

The body shape matches what the original request asked for — typically a JSON document with the tool/LLM result. Concretely:

• LLM async response — the assistant message content the platform should hand back to the conversation.
• Tool async response — the structured tool result, in the same schema your synchronous tool would have returned.
• Managed provider callback — ordered provider messages plus optional metadata, channelData, and NLU data. Managed LLM providers can use this callback path to continue the conversation and to trigger configured managed actions such as hangup or transfer.

Errors (you couldn't produce a result) follow the same envelope as TelAPI's other errors — see Errors. The conversation will see the error and follow its configured error-handling path in the flow.

TOBi callback fields

TOBi callbacks usually include:

Field	Meaning
conversation.identifier.id	Conversation/channel identifier used to correlate the callback. Required.
messages.message[]	Ordered responses. Delphi extracts plain text, HTML-stripped text, or voice message content in sequence.
metadata	Provider metadata forwarded as structured JSON.
channelData	Provider channel data. Use Channel Data Forwarding when that data should become flow, tool, or SIP-facing context.
nluData	Optional intents, entities, and sentiment from the provider.
actions	Optional managed callback actions such as transfer or hangup. See Managed callback actions.

Managed call actions still have to be enabled in the flow. A callback can only drive transfer or hangup behavior that the flow and platform policy allow. For field-level action payloads such as transferTarget, transferSipHeaders, hangupSipHeaders, and bot-operation result fields, see Managed callback actions.

Managed runtime commands

Managed LLM integrations can drive a call through runtime commands. These are not the same as the Flow Designer settings: the settings decide which commands are allowed, while runtime commands are the per-call messages the bot/provider sends while the call is active.

The flow controls permissions through its managed gateway profile:

• gatewayProfile.commandSources — which sources may send commands, for example external_llm.
• gatewayProfile.commandPolicies[] — which command types are allowed, whether they are enabled, and whether confirmation or wait-for-silence behavior applies.
• gatewayProfile.actions — action-specific defaults for managed hangup and transfer.

Common runtime commands:

Command	Key fields	Effect
hangup	reason, waitForSilence, delayBotDisconnectMs	Ends the call after optional playback drain and disconnect delay. See Speech playback and hangup.
transfer	target, message, canConfirm	Requests transfer to a configured or policy-allowed destination.
set_barge_in	enabled	Turns caller barge-in on or off.
set_voice_input	enabled, clearBuffer	Enables/disables voice input and can clear buffered input.
update_stt_config	config	Updates STT runtime configuration for the active call.
update_tts_config	config	Updates TTS runtime configuration for the active call.
set_tts_voice	voice	Changes the active TTS voice.
set_tts_speaking_rate	rate	Changes TTS speaking rate.
play_audio	media	Plays a referenced audio/media item.
send_dtmf	digits	Sends DTMF digits on the call leg.
update_dtmf_config	enabled, maxDigits, timeoutMs, interDigitTimeoutMs, terminator	Updates live DTMF collection for TOBi-managed calls.
update_bot_delay_config	botNoInputTimeoutMs, botNoInputSpeech, botNoInputUrl, botNoInputRetries, botNoInputGiveUpTimeoutMs	Updates comfort-message and final timeout behavior while waiting for bot responses.
set_context	values	Writes runtime context variables.
emit_event	event, payload	Emits a runtime event for downstream handling.

Every command also carries:

{
  "commandId": "optional-id-for-correlation",
  "source": "external_llm",
  "type": "transfer",
  "metadata": {"providerMessageId": "optional"}
}

Example transfer request:

{
  "commandId": "cmd-123",
  "source": "external_llm",
  "type": "transfer",
  "target": "+491701234567",
  "message": "I will connect you to a specialist now.",
  "canConfirm": true
}

Example hangup request:

{
  "commandId": "cmd-124",
  "source": "external_llm",
  "type": "hangup",
  "reason": "conversation_complete",
  "waitForSilence": true
}

Swagger coverage

TelAPI Swagger should document the callback payload that an external provider POSTs to TelAPI. Flow-authoring settings such as transfer method, caller ID, header rules, or hangup farewell defaults belong to the Flow Designer / source-view schema, because users configure them in TelWeb before the call. If a provider sends runtime command objects through a TelAPI webhook body, that command union should be modeled in the OpenAPI schema for that webhook.

For provider-native TOBi-style callback action fields, use Managed callback actions as the reference.

Latency and ordering

• Post back as soon as you have the answer. The conversation is active and waiting — every second between your accept and your callback shows up as latency to the caller.
• Within one conversation, work items are routed in the order Delphi expects them. Don't reorder your callbacks "to be helpful".
• If you produce nothing because the work was cancelled, you don't need to call back; Delphi will time the awaiting marker out.

Operational considerations

• Replay — if the platform was briefly unavailable when you tried to post back, retry with the same token. The platform de-dups on the token within its TTL.
• Out-of-band debugging — if you suspect a callback isn't reaching a live conversation, your platform operator can correlate via the SigNoz trace ID — see SigNoz monitoring.
• Test with short flows first — verify the round trip on a non-production flow before pointing real callers at it.

See also

• Authentication — the WebRTC API-key model (and how it differs from this).
• Errors — error envelope shared across TelAPI surfaces.
• Tools — the tenant-side view of tools, including async ones.