Skip to main content

Webhooks

platform v0.9.11verified 2026-05-14

/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​

The auth used by /api/v1/webhooks/* is not the Authorization: Bearer <api-key> model of the rest of TelAPI. Instead:

  • The callback URL Delphi gave you embeds (or is paired with) a short-lived token that identifies the specific work item.
  • Your POST back includes that token, in the URL, a header, or the body — whichever the original request told you.
  • The token is one-shot (per work item) and scoped to that conversation/turn.
  • If the conversation has already ended or the token has been used, the platform rejects the callback.

The exact header / parameter names will be enumerated in the generated reference; the shape is stable but the field names should not be hard-coded from documentation — pull them from the original request payload Delphi sent you.

Do not log callback tokens

Treat the callback token like a one-shot bearer credential. 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.