Webhooks API

BrokerOS exposes public webhook endpoints to receive real-time events from external marketing networks, PSTN telecom carriers, AI voice engines, and ad platforms. All webhook endpoints process events asynchronously to guarantee rapid 200 OK acknowledgment to third-party providers.

Webhook Endpoints Directory

Channel	Endpoint	Provider / Source	Purpose
Meta Ads	`GET/POST /api/marketing/ads/meta/webhooks`	Facebook & Instagram Lead Ads	Hub verification & instant lead ingestion
Google Ads	`POST /api/marketing/ads/google/webhooks`	Google Search / YouTube Lead Forms	Ingest leads from Google Ads extensions
WhatsApp	`GET/POST /api/marketing/whatsapp/webhook`	Meta Cloud API	Token challenge, inbound messages & delivery receipts
Voice AI	`POST /api/marketing/voice/webhooks/:provider`	Vapi, Retell, Sarvam, ElevenLabs	Call ended, transcript, and sentiment analysis
Marketing Telephony	`GET/POST /api/marketing/voice/webhooks/:carrier-answer`	Vobiz, Twilio, Telnyx	Call pickup XML / TeXML media stream bridge
CRM Softphone	`POST /api/crm/telephony/webhooks/:event`	Twilio, Telnyx, Exotel, Vobiz	Softphone TwiML, status callbacks, recording upload & AI transcription
SMS	`POST /api/marketing/sms/webhooks/:provider`	Gupshup, Twilio, Sinch, AWS SNS	Delivery receipts (DLR) and failure notifications
Email	`POST /api/marketing/email/webhooks/:provider`	SendGrid, Brevo, AWS SES, Mailchimp	Opens, clicks, bounces, and spam complaints

1. Meta Lead Ads Webhook

Used by Meta’s Graph API to push leads the moment a user submits a form on Facebook or Instagram.

Verification Handshake (GET)

GET /api/marketing/ads/meta/webhooks?hub.mode=subscribe&hub.verify_token=brokeros_meta_verify_token&hub.challenge=1158201444

BrokerOS validates hub.verify_token against the META_WEBHOOK_VERIFY_TOKEN environment variable and returns hub.challenge with HTTP 200.

Event Payload (POST)

POST /api/marketing/ads/meta/webhooks
Content-Type: application/json
X-Hub-Signature-256: sha256=...

{
  "object": "page",
  "entry": [
    {
      "id": "109823471029384",
      "time": 1759300000,
      "changes": [
        {
          "field": "leadgen",
          "value": {
            "ad_id": "23851029384750123",
            "form_id": "182736450192837",
            "leadgen_id": "981273049182374",
            "created_time": 1759300000,
            "page_id": "109823471029384"
          }
        }
      ]
    }
  ]
}

The server automatically queries Meta Graph API for field values (Name, Phone, Email, Budget, Project Interest) and instantiates a new CRM Lead.

2. Voice Agent & Carrier Webhooks

Carrier Call Answer XML (Twilio / Vobiz / Telnyx)

When an outbound call placed via PSTN carrier connects to the customer’s phone, the carrier requests call instructions from BrokerOS:

POST /api/marketing/voice/webhooks/vobiz-answer?campaignId=cm123&recipientId=rcp456

Response (Vobiz XML)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Speak>Hello! Thank you for connecting with us from BrokerOS. Your voice session is active.</Speak>
</Response>

Response (Telnyx TeXML WebSocket Stream)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://api.yourdomain.com/voice/stream">
      <Parameter name="campaignId" value="cm123"/>
      <Parameter name="agent" value="VAPI"/>
    </Stream>
  </Connect>
</Response>

Voice Platform Event Webhook

When the AI agent terminates the call, Vapi or Retell sends call analytics:

POST /api/marketing/voice/webhooks/vapi

{
  "message": {
    "type": "end-of-call-report",
    "call": {
      "id": "c1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
      "status": "ended",
      "duration": 182
    },
    "transcript": "AI: Hello Mr. Sharma... User: Yes I am looking for a 3BHK...",
    "summary": "Customer confirmed interest in Emerald Heights Tower B. Requested callback on Saturday.",
    "analysis": {
      "userSentiment": "Positive",
      "successEvaluation": "true"
    },
    "recordingUrl": "https://storage.vapi.ai/recordings/call-123.mp3"
  }
}

3. WhatsApp Meta Cloud API Webhook

POST /api/marketing/whatsapp/webhook

Receives real-time message status updates (sent, delivered, read, failed) and inbound customer replies. Updates are dispatched over the Socket.IO whatsapp-realtime.gateway.ts to reflect instantly on the web and mobile team inboxes.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID_001",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "919800000000", "phone_number_id": "PHONE_ID_001" },
            "contacts": [{ "profile": { "name": "Vikram Patel" }, "wa_id": "919876543210" }],
            "messages": [
              {
                "from": "919876543210",
                "id": "wamid.HBgLM...",
                "timestamp": "1759300000",
                "text": { "body": "Please share the site visit location pin" },
                "type": "text"
              }
            ]
          }
        }
      ]
    }
  ]
}

4. CRM In-Browser Telephony & Softphone Webhooks

Managed by CrmTelephonyWebhooksController to handle softphone dialing, duration tracking, and call recording uploads:

Twilio Voice Dial TwiML (POST)

POST /api/crm/telephony/webhooks/twilio-voice

Called by Twilio when an in-browser WebRTC agent clicks to call a lead. Responds with dynamic TwiML enabling dual-channel recording and status callbacks:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="+12025550199" record="record-from-answer-dual" recordingStatusCallback="https://api.yourdomain.com/api/crm/telephony/webhooks/twilio-recording?callRecordId=rec_123">
    <Number statusCallback="https://api.yourdomain.com/api/crm/telephony/webhooks/twilio-status?callRecordId=rec_123" statusCallbackEvent="initiated ringing answered completed">+12025550144</Number>
  </Dial>
</Response>

Twilio Recording Callback (POST)

POST /api/crm/telephony/webhooks/twilio-recording?callRecordId=rec_123

Carrier delivers recording URL upon call completion:

Server downloads audio buffer using authenticated Basic Auth.
Streams audio to Vercel Blob storage (calls/:targetId-:timestamp-:id.mp3).
Resets User.isOnCall = false.
Enqueues Groq Whisper AI transcription, next step extraction, and non-destructive lead profile updates.

System Architecture

API Reference

Webhook Endpoints Directory

1. Meta Lead Ads Webhook

Verification Handshake (GET)

Event Payload (POST)

2. Voice Agent & Carrier Webhooks

Carrier Call Answer XML (Twilio / Vobiz / Telnyx)

Response (Vobiz XML)

Response (Telnyx TeXML WebSocket Stream)

Voice Platform Event Webhook

3. WhatsApp Meta Cloud API Webhook

4. CRM In-Browser Telephony & Softphone Webhooks

Twilio Voice Dial TwiML (POST)

Twilio Recording Callback (POST)

​Webhook Endpoints Directory

​1. Meta Lead Ads Webhook

​Verification Handshake (GET)

​Event Payload (POST)

​2. Voice Agent & Carrier Webhooks

​Carrier Call Answer XML (Twilio / Vobiz / Telnyx)

​Response (Vobiz XML)

​Response (Telnyx TeXML WebSocket Stream)

​Voice Platform Event Webhook

​3. WhatsApp Meta Cloud API Webhook

​4. CRM In-Browser Telephony & Softphone Webhooks

​Twilio Voice Dial TwiML (POST)

​Twilio Recording Callback (POST)

Webhook Endpoints Directory

1. Meta Lead Ads Webhook

Verification Handshake (GET)

Event Payload (POST)

2. Voice Agent & Carrier Webhooks

Carrier Call Answer XML (Twilio / Vobiz / Telnyx)

Response (Vobiz XML)

Response (Telnyx TeXML WebSocket Stream)

Voice Platform Event Webhook

3. WhatsApp Meta Cloud API Webhook

4. CRM In-Browser Telephony & Softphone Webhooks

Twilio Voice Dial TwiML (POST)

Twilio Recording Callback (POST)