Skip to content

Commit a2c1858

Browse files
VAP15-53 docs: document webhook credential withholding
VAPSEC-564/619/623 changed a documented contract: when a server URL arrives in the API request itself - a transient assistant, or assistantOverrides - Vapi no longer attaches the org's webhook credential, and credential fields in the payload arrive as [REDACTED]. The page still promised the old behavior, so a customer hitting this sees an unauthenticated webhook and no explanation, indistinguishable from a broken listener. Adds three things to fern/server-url/server-authentication.mdx: - A Quick start warning, so the "Vapi will now authenticate requests" promise carries its condition where a reader meets it rather than 300 lines later. - A "When credentials are not attached" section: which paths are caller-authored, the contrast that saved assistants, phone numbers and tools keep their credentials, and the [REDACTED] payload note. - "Confirming a withheld send in your logs", carrying what support needs: the literal log string, the suppressed high-volume message types, and the trap that a missing entry does not mean credentials were sent. The rollout qualifier is not optional polish. Without it the page states the withholding unconditionally while pre-cutoff orgs are still gated by ENABLE_WEBHOOK_CREDENTIAL_BINDING, so an unenrolled org could read "no X-Vapi-Secret header" and conclude its secret is not reaching a third-party URL when it still is - an inaccuracy in the unsafe direction. It deliberately does not invite enrollment requests; the ramp is a hand-maintained list with limited slots, mostly allocated. ENFORCEMENT_DATE_TBD is a literal placeholder and a merge blocker. The VAPSEC-689 cutoff is still being settled with the CISO, infosec and the EM. A non-rendering MDX comment marks the spot. Scoped to the webhook server URL. The message-options override paths (tools, KB, custom voice, handoff and transfer destinations, endpointing) are VAPSEC-627 and are documented separately in VAP15-54. fern check: 0 errors, 12 pre-existing discriminator warnings. Refs VAP15-53, VAPSEC-564, VAPSEC-619, VAPSEC-623, VAPSEC-689 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 786d1a2 commit a2c1858

1 file changed

Lines changed: 44 additions & 0 deletions

File tree

‎fern/server-url/server-authentication.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,10 @@ This replaces the previous inline authentication approach and provides better se
5757
</Step>
5858
</Steps>
5959

60+
<Warning>
61+
Credentials configured for your org are attached only when the server URL also comes from your org configuration (a saved assistant, phone number, tool, or your org's server settings). When the server URL is included in the API request itself, then Vapi will send the webhook **without** your org's configured credential. See [When credentials are not attached](#when-credentials-are-not-attached).
62+
</Warning>
63+
6064
## Creating Custom Credentials
6165

6266
### Dashboard Management
@@ -380,6 +384,46 @@ const tool = await client.tools.create({
380384
```
381385
</CodeBlocks>
382386

387+
### When credentials are not attached
388+
389+
Vapi attaches your org's credential only to webhook server URLs **in your org configuration**. A server URL supplied in the API request itself has the webhook sent to it without your configured org credential (no `credentialId` lookup, no `X-Vapi-Secret` header, no `Authorization` header).
390+
391+
This applies when the API request server URL comes from:
392+
393+
- a transient `assistant` passed inline to `POST /call`, `POST /chat`, or `POST /session`
394+
- `assistantOverrides` on a call, chat, or session
395+
396+
It does **not** apply to a saved assistant, phone number, or tool, or to your org's Server Configuration - those keep their credentials.
397+
398+
{/* TODO(VAP15-53): replace ENFORCEMENT_DATE_TBD with the VAPSEC-689 cutoff date
399+
(WEBHOOK_CREDENTIAL_BINDING_CUTOFF) once CISO / infosec / EM sign off. Do not merge
400+
with the placeholder in place. */}
401+
402+
<Warning>
403+
These rules apply to all new organizations - those created on or after ENFORCEMENT_DATE_TBD. To minimize disruption to legacy organizations created before that date, we are applying this change as a phased rollout. For legacy orgs, your org's credential will still be included with server URLs supplied in the request until the rollout reaches your org.
404+
</Warning>
405+
406+
<Warning>
407+
If you supply the server URL in your API request, your endpoint receiving the webhook must enforce your own authentication. Either include the credential in your API request's `server.headers` parameters, or configure the URL on a saved resource instead, so that your org credential can be sent with it in the webhook.
408+
</Warning>
409+
410+
Webhooks sent to a server URL supplied in the API request also have credential fields stripped 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.
411+
412+
#### Confirming a withheld send in your logs
413+
414+
When Vapi withholds credentials, it also writes an entry to the call's webhook logs:
415+
416+
```
417+
Assistant credentials withheld from <messageType>: this server url came from an
418+
assistant this request supplied, not from your org configuration
419+
```
420+
421+
The entry is written **once per message type, not once per send**. It is suppressed for the high-volume message types - `model-output`, `speech-update`, `status-update`, `transcript`, `transcript[transcriptType="final"]`, `voice-input`, and `voice-request`.
422+
423+
<Warning>
424+
Absence of the webhook call log entry on a suppressed type does **not** mean credentials were sent. Credential withholding always happens on this path; only the log entry is suppressed. Check `end-of-call-report`, `call.artifact.upload`, or the session and chat webhooks - at least one of these is logged on every affected call.
425+
</Warning>
426+
383427
## Credential Management
384428

385429
### Dashboard Features

0 commit comments

Comments
 (0)