Docs

Vapi, Retell & Twilio

Instead of calling the API yourself, a voice platform can push each finished call to a signed webhook URL. Create a connection in Settings & API → Voice platform connections (organization owners and admins). Each connection has its own URL:

https://goldnovaai.com/api/webhooks/<vapi|retell|twilio>/<connection id>

	Authentication	What creates a call	Transcript
Vapi	A secret generated by us, shown once (only its SHA-256 is stored). Sent as `Authorization: Bearer <secret>` or `X-Vapi-Secret`.	`end-of-call-report` only; other messages are acknowledged and ignored.	From the message list (assistant/bot → agent, user → customer), else the transcript text.
Retell	`x-retell-signature`: HMAC-SHA256 with your API key (webhook badge), within ±5 minutes. The key is stored encrypted.	`call_ended` and `call_analyzed` (the second is an idempotent duplicate).	From `transcript_object` with word timings.
Twilio	`X-Twilio-Signature`: HMAC-SHA1 with your Auth Token over the URL and sorted parameters. Account SID and Auth Token; the token is stored encrypted.	A recording status callback with `RecordingStatus=completed`; `externalCallId` is the RecordingSid.	The audio is downloaded from api.twilio.com and transcribed; there are no speaker labels, so speaker-dependent rules report “Review recommended”. Counts against the audio and call allowances.

Behaviour

400 body is not valid JSON; 401 invalid_signature; 404 unknown or disconnected connection; 413 body too large; 422 structurally invalid payload; 429 rate limit (300 verified call events per minute per connection); 500/503 temporary server-side failure (the provider may retry).
Twilio: the callback URL you give Twilio must be exactly the URL shown in Settings, because the signature covers it; otherwise every delivery is refused with 401. If the recording cannot be downloaded from Twilio after retries, the call is marked failed and Twilio is not asked to redeliver (it already received a success response): replay the callback from Twilio or record again.
200 for events that are acknowledged but ignored, duplicates, calls refused because the allowance is used up (so the provider does not retry), and re-deliveries whose content differs from the stored call (the stored call and its evidence are kept).
Customer phone numbers in provider payloads are never stored. Metadata is limited to the end reason, call type and, for Twilio, the call SID, channel count and source.
Vapi has one Server URL per assistant: pointing it at GoldNovaAI replaces any server URL you already use for tool calls.