Skip to main content
When an outbound telephone conversation concludes, the AI platform or telephony carrier transmits a structured webhook payload back to BrokerOS. This payload contains essential intelligence: the recorded audio MP3 URL, turn-by-turn conversational transcript, duration in seconds, cost metrics, and extracted customer sentiment. The Voice Webhook Controller (VoiceWebhooksController.ts) and Webhook Diagnostics Card (VoiceWebhookDiagnostics.tsx) provide full transparency into webhook routing, signature validation, and payload processing.

​
Webhook Ingestion & CRM State Synchronization

​
The 7 Core Webhook Endpoints

BrokerOS maintains dedicated webhook endpoints catering to both telephony call routing and post-call analytics:

​
Real-Time Webhook Diagnostic Simulator

Connecting and testing webhooks across live telephony providers can be cumbersome during development. The Voice Webhook Diagnostics Studio (VoiceWebhookDiagnostics.tsx) includes an interactive simulation suite built directly into the marketing settings page:

Simulated AI Platform

Select target platform schema: Vapi, Retell, ElevenLabs, or Sarvam.

Simulated Recipient Phone

Enter any test phone number (e.g., +919876543210) to simulate an inbound event.

Sentiment Override

Test POSITIVE, NEUTRAL, or NEGATIVE sentiment processing.

Executive AI Summary

Input a synthetic conversation summary describing unit interest and site visit booking requests.

​
Simulation Execution

Clicking Dispatch Simulated Webhook performs an end-to-end test against /api/marketing/voice/webhooks/:provider:
  1. Generates a valid JSON payload matching the selected platform’s official schema.
  2. Dispatches an authenticated HTTP POST request to the local or production webhook endpoint.
  3. Verifies that the recipient status advances to COMPLETED, the call log is created, and the corresponding CRM Lead temperature updates to HOT.
  4. Renders the raw HTTP response code and parsed event count directly in the interface.

​
Security & Signature Verification

To prevent unauthorized actors from spoofing call completions or tampering with lead ratings, BrokerOS enforces cryptographic validation across all webhook channels:
  • HMAC-SHA256 Signatures: Platforms like Retell and ElevenLabs sign request payloads using an HMAC secret key transmitted in HTTP headers (e.g., x-retell-signature). BrokerOS recomputes the hash using the stored secret and rejects mismatched requests with HTTP 401 Unauthorized.
  • Vapi Server Secret: Vapi requests validate against the configured serverUrlSecret credential.
  • Telecom IP Whitelisting: Carrier answer callbacks verify source IP addresses and basic authentication parameters before executing telecommunication media streams.