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", that's not a current v0.9.11 capability — TelWeb is the canonical surface for conversation history today. Watch Release notes for outbound events.

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 a v0.9.11 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. 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.

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.

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.