diff --git a/fern/server-url/server-authentication.mdx b/fern/server-url/server-authentication.mdx index 1b21996aa..0309460f7 100644 --- a/fern/server-url/server-authentication.mdx +++ b/fern/server-url/server-authentication.mdx @@ -405,6 +405,25 @@ If you supply the server URL in your API request, your endpoint must authenticat For webhooks sent to a server URL supplied in the API request, Vapi also strips credential fields from the payload. Any `apiKey`, `secret`, `password`, `authToken`, or similar field on the embedded `assistant`, `session`, or `chat` object arrives as the string `"[REDACTED]"` rather than its real value. The rest of the payload is unchanged. +#### Subsystem server URLs + +Some webhooks go to a URL owned by a subsystem rather than to your assistant's webhook URL. Tools, knowledge bases, custom voices, dynamic handoff and transfer destinations, and custom endpointing providers each carry their own `server` block: + +| Webhook | Server it is sent to | +| --- | --- | +| `tool-calls`, `function-call` | the tool's | +| `knowledge-base-request` | the knowledge base's | +| `voice-request` | the custom voice's | +| `handoff-destination-request` | the handoff destination's | +| `transfer-destination-request` | the transfer destination's | +| `call.endpointing.request` | the endpointing provider's | + +**These follow the assistant that carried them.** A tool on a saved assistant is org-configured and keeps your credentials. The same tool on a transient assistant or in `assistantOverrides` is caller-authored, and Vapi sends to its URL without them. + + +A saved assistant can carry a caller-authored subsystem server: if `assistantOverrides` replaces the voice, the tools, or the knowledge base, those replacements are caller-authored even though the assistant itself is saved. Give any subsystem server you supply in a request its own authentication in that block's `headers`. + + #### Confirming a withheld send in your logs When Vapi withholds credentials, it also writes an entry to the call's webhook logs: diff --git a/fern/squads/handoff/destinations.mdx b/fern/squads/handoff/destinations.mdx index 056b93522..bd8ba7711 100644 --- a/fern/squads/handoff/destinations.mdx +++ b/fern/squads/handoff/destinations.mdx @@ -149,6 +149,10 @@ Best for Anthropic models -- single tool with multiple destination options: The destination is determined at runtime via the `handoff-destination-request` webhook: + +A destination's `server` block follows the assistant carrying it. On a saved assistant it keeps your org's webhook credentials; supplied through a transient assistant or `assistantOverrides` it is caller-authored, and Vapi sends to it without them. Give it its own authentication in `server.headers`, as the examples below do. See [Server authentication](/server-url/server-authentication#subsystem-server-urls). + + ```json { "tools": [ @@ -217,7 +221,10 @@ Pass additional context to your webhook for intelligent routing: { "type": "dynamic", "server": { - "url": "https://api.example.com/intelligent-routing" + "url": "https://api.example.com/intelligent-routing", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } } } ],