> ## Documentation Index
> Fetch the complete documentation index at: https://brokeros.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks API

> Inbound webhook endpoints for ad platforms, WhatsApp, AI voice platforms, SMS gateways, and email providers.

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)

```http theme={null}
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)

```http theme={null}
POST /api/marketing/ads/meta/webhooks
Content-Type: application/json
X-Hub-Signature-256: sha256=...
```

```json theme={null}
{
  "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:

```http theme={null}
POST /api/marketing/voice/webhooks/vobiz-answer?campaignId=cm123&recipientId=rcp456
```

#### Response (Vobiz XML)

```xml theme={null}
<?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 theme={null}
<?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:

```http theme={null}
POST /api/marketing/voice/webhooks/vapi
```

```json theme={null}
{
  "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

```http theme={null}
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.

```json theme={null}
{
  "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`](https://github.com/trybrokeros/BrokerOS/blob/main/apps/api/src/crm-telephony/crm-telephony-webhooks.controller.ts) to handle softphone dialing, duration tracking, and call recording uploads:

### Twilio Voice Dial TwiML (POST)

```http theme={null}
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 theme={null}
<?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)

```http theme={null}
POST /api/crm/telephony/webhooks/twilio-recording?callRecordId=rec_123
```

Carrier delivers recording URL upon call completion:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.