diff --git a/fern/server-url/server-authentication.mdx b/fern/server-url/server-authentication.mdx index ba90e241a..8e75ddd02 100644 --- a/fern/server-url/server-authentication.mdx +++ b/fern/server-url/server-authentication.mdx @@ -405,6 +405,31 @@ 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 + +Tools, knowledge bases, custom voices, handoff and transfer destinations, and custom endpointing providers each carry their own `server` block. These requests go to that block's URL, not to your assistant's webhook URL: + +- `tool-calls` and `function-call`, to the tool's server +- `knowledge-base-request`, to the knowledge base's server +- `voice-request`, to the custom voice's server +- `handoff-destination-request` and `transfer-destination-request`, to the destination's server +- `call.endpointing.request`, to the endpointing provider's server +- `apiRequest` tool requests, to the tool's URL +- MCP requests, to the MCP server's URL, both when Vapi lists its tools at call start and on each tool call + +When a transient assistant or `assistantOverrides` supplies a server URL or `credentialId` for any of these, Vapi withholds your org credential from **every** request in this list whose URL differs from your assistant's webhook URL. On a withheld request: + +- your org's `secret`, `headers`, and credential are not sent +- a `credentialId` in the request is ignored, because it points at a credential stored in your org +- the `secret` and `headers` you set in that `server` block are still sent +- credential fields in the payload arrive as `"[REDACTED]"` + +Overrides that set only `variableValues` don't trigger this. In chats, the setting lasts for the whole session, including resumed sessions and handoffs. + + +Supplying one tool, voice, or knowledge base through `assistantOverrides` also withholds your org credential from the saved assistant's own tools, voice, and knowledge base. Put authentication for those endpoints in their `server.headers`, or move the override onto a saved assistant. + + #### Confirming a withheld send in your logs When Vapi withholds credentials, it also writes an entry to the call's logs: @@ -413,7 +438,13 @@ When Vapi withholds credentials, it also writes an entry to the call's logs: Assistant credentials withheld from : this server url came from an assistant this request supplied, not from your org configuration ``` -Open the call in [**Calls**](/observability/logs/call-logs) under **Logs**. On its **Logs** tab, search for `credentials withheld`. Leave the category filter unset: the entry is not always filed under **Webhook**. +For a tool, custom voice, or MCP request withheld under [Subsystem server URLs](#subsystem-server-urls), the entry reads: + +```text +Assistant credentials withheld from : this assistant carries server configuration this request supplied +``` + +Open the call in [**Calls**](/observability/logs/call-logs) under **Logs**. On its **Logs** tab, search for `credentials withheld`, which matches both entries. Leave the category filter unset: the entry is not always filed under **Webhook**. Vapi writes the entry **on each send** of a message type that is not suppressed. The same entry can repeat within a call. Vapi suppresses it for high-volume message types: `model-output`, `speech-update`, `status-update`, `transcript`, `transcript[transcriptType="final"]`, `voice-input`, and `voice-request`. diff --git a/fern/squads/handoff/destinations.mdx b/fern/squads/handoff/destinations.mdx index b647c1f29..9b6102ea0 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: + +If a transient assistant or `assistantOverrides` supplies any tool, voice, or destination server, Vapi sends `handoff-destination-request` without your org credential. Put authentication in `server.headers`, as these examples do; see [Subsystem server URLs](/server-url/server-authentication#subsystem-server-urls). + + ```json { "tools": [ @@ -160,7 +164,7 @@ The destination is determined at runtime via the `handoff-destination-request` w "server": { "url": "https://api.example.com/determine-handoff-destination", "headers": { - "Authorization": "Bearer YOUR_API_KEY" + "Authorization": "Bearer YOUR_WEBHOOK_TOKEN" } } } @@ -219,7 +223,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_WEBHOOK_TOKEN" + } } } ],