Skip to content

VAP15-54 docs: document subsystem server credentials #1223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jeffrey-hoekman-vapi wants to merge 2 commits into
base: jeffhoekman/vap15-53-webhook-credentials-withheld-caller-supplied-server-url
Choose a base branch
from
+27 −1
Draft

VAP15-54 docs: document subsystem server credentials #1223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76b3bd2
VAP15-54 docs: document subsystem server credentials
jeffrey-hoekman-vapi Sep 8, 2026
11f7f9f
VAP15-54 docs: drop the spaced hyphen in the subsystem intro
jeffrey-hoekman-vapi Sep 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions fern/server-url/server-authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

@corey-vapi-ai corey-vapi-ai Sep 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider a one-dimensional list here, unless you feel that makes the behavior of function-call unclear

| --- | --- |
| `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.

<Warning>
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`.
</Warning>

#### Confirming a withheld send in your logs

When Vapi withholds credentials, it also writes an entry to the call's webhook logs:
Expand Down
9 changes: 8 additions & 1 deletion fern/squads/handoff/destinations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

<Warning>
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).
</Warning>

```json
{
"tools": [
Expand Down Expand Up @@ -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"
}
}
}
],
Expand Down
Loading