Custom CRM Webhook Architecture for AI Calling — Developer's Guide

Q: Our CRM is a legacy system with no formal API. What is the minimum integration we can build to connect AI calling?

The absolute minimum viable integration requires two capabilities: (1) a mechanism to push new lead records (including phone number and project interest) to the AI Calling Agent when they are created — this can be a simple HTTP POST from a CRM trigger or a cron job running every 2 minutes pulling new leads from a database view; (2) a writable endpoint or database table where the AI Calling Agent can write disposition data. Even a CSV export + import cycle works as a proof-of-concept, though real-time webhook architecture is strongly preferred for production deployments.

Q: How do we handle the scenario where the AI calls a lead but the CRM has already been updated by a human BDR concurrently?

Implement an optimistic concurrency check in the disposition endpoint: include the lead's last_modified_at timestamp in the disposition request payload. The CRM endpoint checks whether the record has been modified after the AI call was initiated — if it has, the endpoint returns HTTP 409 (Conflict) and the AI logs the conflict for manual review rather than overwriting human-entered data.

Q: Can the custom CRM integration support multiple AI Calling Agent instances running simultaneously for different projects?

Yes. The project_id field in the webhook payload routes each lead to the correct AI agent instance with the matching qualification script. The disposition write-back includes the project_id so the CRM can route data to the correct project pipeline. Multiple concurrent AI agent instances writing to the same CRM endpoint is standard architecture — the CRM must handle concurrent writes through proper database transaction management.

Q: Do we need a message queue (Redis/SQS) for a mid-size deployment, or is direct API integration sufficient?

Direct API integration is sufficient for most deployments under 200 concurrent calls, provided the CRM's disposition endpoint meets the P99 response time and error rate benchmarks. A queuing layer becomes necessary once concurrent call volume during peak launches (500+ simultaneous calls) exceeds what the CRM's database can sustain without lock contention or timeout errors — at that point, the queue decouples AI write speed from CRM write throughput.

Q: What happens to a disposition write if it fails all 5 retry attempts?

It is written to a dead-letter queue and flagged for manual disposition — the engineering team is alerted, and the qualification data (budget, BHK preference, site visit booking, call recording) is preserved outside the CRM until the record can be manually reconciled or the write replayed once the CRM recovers. This prevents permanent loss of a completed qualification call's data.

Zappio Team

AI & Real Estate Experts · 27 June 2026 · 12 min read

CRM Integration · Platform-Specific Deep Dives

No Pre-Built Connector for Your CRM? Here Is the Webhook Architecture to Build Yourself

A significant portion of India's largest real estate developer groups do not run their sales operations on Sell.Do, LeadSquared, or Salesforce. They run on proprietary, internally-built CRM systems — custom-developed platforms built by their in-house technology teams or external software vendors, often years ago, and evolved through layers of customization to serve specific business workflows. These bespoke systems cannot use pre-built CRM connectors. They require a custom webhook architecture that connects the AI Calling Agent to the developer's proprietary lead management infrastructure.

This article is written for the solution architects, engineering leads, and CTO-level technologists at real estate developer groups who need to build and maintain this integration themselves. It covers the complete webhook + API architecture, the data contract between systems, error handling and retry logic, and the security considerations specific to voice AI integrations handling PII in real estate sales contexts.

The Core Integration Contract: What Both Systems Must Agree On

Before writing a single line of code, the AI Calling Agent platform and the custom CRM must establish a data contract — a shared agreement on the format, schema, and timing of data exchange. Getting this contract wrong creates silent data corruption: leads are called but disposition data writes to the wrong fields; site visits are booked but the CRM shows no record; DNC flags are set but the system re-dials the next day.

The data contract covers three interaction points:

Lead Push (CRM → AI Calling Agent) — the CRM notifies the AI Calling Agent when a new lead requires qualification
Status Query (AI Calling Agent → CRM) — the AI Calling Agent checks lead status before calling, to avoid calling already-qualified or DNC leads
Disposition Write-Back (AI Calling Agent → CRM) — the AI Calling Agent writes structured qualification data back to the CRM upon call completion

Part 1 — Lead Push Architecture (CRM → AI Calling Agent)

The CRM fires a webhook to the AI Calling Agent's inbound endpoint upon lead creation or when a lead enters the "to be called" queue. The webhook payload must be minimal, complete, and idempotent.

{
  "event": "lead.created",
  "timestamp": "2026-07-01T14:32:00+05:30",
  "idempotency_key": "CRM-LEAD-20260701-001234",
  "lead": {
    "id": "CRM-LEAD-001234",
    "phone": "+919800000000",
    "phone_alt": "+919700000000",
    "name": "Arjun Kapoor",
    "source": "99acres",
    "campaign_id": "META-JUN26-DWK",
    "project_interest": "Dwarka Expressway 3BHK",
    "project_id": "PROJ-DWK-PHASE2",
    "language_preference": "hindi",
    "created_at": "2026-07-01T14:31:55+05:30",
    "call_priority": "high"
  }
}

Critical design decisions in the lead push:

idempotency_key — the CRM must generate a unique key per lead event. The AI Calling Agent uses this to deduplicate — if the same webhook fires twice (network retry), only one call is initiated
phone format — always E.164 format (+91XXXXXXXXXX). Never send unformatted 10-digit numbers — the AI Calling Agent's telephony layer requires E.164
project_id — include a CRM-native project identifier, not just a human-readable string. The AI Calling Agent uses project_id to select the correct qualification script from its script library
call_priority — allows the CRM to signal urgency. A lead from a developer's own website calls within 60 seconds; a bulk-uploaded old lead list enters a batched queue

The CRM must authenticate its webhook requests to prevent unauthorized lead injection, using an HMAC signature and timestamp header. The AI Calling Agent validates the HMAC signature against the shared secret, confirms the timestamp is within ±5 minutes (preventing replay attacks), and confirms the idempotency_key has not been processed in the last 24 hours.

Part 2 — Pre-Call Status Query (AI Calling Agent → CRM)

Before initiating any call, the AI Calling Agent must query the CRM to confirm the lead is still in a callable state. This prevents calling a lead a human BDR already qualified 30 minutes ago, calling a lead manually marked DNC after form submission, or calling a lead already marked "Booked" in high-concurrency launch scenarios.

GET /api/leads/{lead_id}/status
Authorization: Bearer {ai_agent_api_key}

Response:
{
  "lead_id": "CRM-LEAD-001234",
  "callable": true,
  "status": "new",
  "dnc": false,
  "human_contacted": false,
  "last_call_attempt": null
}

If callable: false is returned, the AI Calling Agent logs a suppression event and does not initiate the call. This query adds ~50ms latency before call initiation — negligible against the 90-second first-contact target.

Part 3 — Disposition Write-Back (AI Calling Agent → CRM)

This is the most critical integration surface. The AI Calling Agent must write structured disposition data to the CRM within 30 seconds of call completion — while the buyer's data is fresh and before any human agent views the record.

POST /api/leads/{lead_id}/disposition
{
  "call_metadata": {
    "call_id": "ZAP-CALL-20260701-XXXX",
    "duration_seconds": 306,
    "recording_url": "https://storage.zappio.ai/recordings/ZAP-CALL-XXXX.mp3",
    "transcript_url": "https://storage.zappio.ai/transcripts/ZAP-CALL-XXXX.json"
  },
  "qualification": {
    "outcome": "qualified_visit_booked",
    "ai_intent_score": 82,
    "budget_min": 8500000,
    "budget_max": 12000000,
    "bhk_preference": "3BHK",
    "possession_timeline": "18_months",
    "loan_required": true,
    "purchase_intent": "end_use",
    "nri_flag": false
  },
  "site_visit": {
    "booked": true,
    "date": "2026-07-05",
    "time_slot": "11:00",
    "timezone": "Asia/Kolkata"
  },
  "flags": {
    "dnc_requested": false,
    "duplicate_detected": false,
    "language_used": "hindi"
  }
}

Outcome enum values the CRM must handle: qualified_visit_booked, qualified_no_visit, callback_requested, not_interested_budget, not_interested_location, not_interested_timeline, already_purchased, wrong_number, dnc_requested, no_answer, invalid_number, and duplicate_suppressed.

Error Handling and Retry Architecture

Custom CRM endpoints will occasionally fail — network timeouts, database locks during high-concurrency launch periods, or deployment downtime. The AI Calling Agent must implement a robust retry pattern to prevent disposition data loss:

Attempt	Delay	Action on Failure
1 (immediate)	0s	Write disposition data
2	30s	Retry if HTTP 5xx or timeout
3	2 minutes	Retry if still failing
4	10 minutes	Retry
5	60 minutes	Final retry
After 5 failures	—	Write to dead-letter queue; alert engineering team; flag lead for manual disposition

💡

The dead-letter queue is non-negotiable — every disposition write failure must be captured somewhere so it can be replayed once the CRM recovers. Disposition data lost permanently means a qualified lead with a booked site visit has no CRM record of either — a high-cost operational failure.

Security Architecture: PII Protection in Voice AI Integrations

Real estate sales calls capture significant PII: full name, mobile number, home address, employment details, income indicators, and family information. The integration architecture must handle this data in compliance with India's Digital Personal Data Protection (DPDP) Act, 2023:

Data minimization — the AI Calling Agent transmits only the PII fields necessary for CRM operation, no unnecessary enrichment data
Encryption in transit — all API calls between AI Calling Agent and CRM use TLS 1.2+, no HTTP
Recording storage — call recordings stored in AI platform storage (not transmitted to CRM raw); only a secure URL is passed to the CRM
Retention policy — recording and transcript URLs must expire after the retention period defined in your DPDP consent framework (typically 90–180 days)
DNC data handling — if a buyer requests DNC during an AI call, the flag must propagate to the CRM within the same disposition write-back, with no acceptable delay

Performance Benchmarks for Custom CRM Endpoints

For the AI Calling Agent to maintain its 90-second first-contact SLA during peak launch periods (500–1,000 concurrent calls), the CRM's integration endpoints must meet minimum performance requirements:

Endpoint	Maximum Response Time (P99)	Maximum Error Rate
GET /leads/{id}/status	200ms	< 0.1%
POST /leads/{id}/disposition	500ms	< 0.5%
Webhook receipt acknowledgment	2,000ms	< 0.1%

If these thresholds cannot be met under peak load, the integration architecture must include a queuing layer (Redis, AWS SQS, or RabbitMQ) between the AI Calling Agent and the CRM endpoint — the AI writes dispositions to the queue instantly, and a consumer service writes to the CRM at the CRM's sustainable throughput rate.

Frequently Asked Questions

The absolute minimum viable integration requires two capabilities: (1) a mechanism to push new lead records (including phone number and project interest) to the AI Calling Agent when they are created — this can be a simple HTTP POST from a CRM trigger or a cron job running every 2 minutes pulling new leads from a database view; (2) a writable endpoint or database table where the AI Calling Agent can write disposition data. Even a CSV export + import cycle works as a proof-of-concept, though real-time webhook architecture is strongly preferred for production deployments.

Implement an optimistic concurrency check in the disposition endpoint: include the lead's last_modified_at timestamp in the disposition request payload. The CRM endpoint checks whether the record has been modified after the AI call was initiated — if it has, the endpoint returns HTTP 409 (Conflict) and the AI logs the conflict for manual review rather than overwriting human-entered data.

Yes. The project_id field in the webhook payload routes each lead to the correct AI agent instance with the matching qualification script. The disposition write-back includes the project_id so the CRM can route data to the correct project pipeline. Multiple concurrent AI agent instances writing to the same CRM endpoint is standard architecture — the CRM must handle concurrent writes through proper database transaction management.

Direct API integration is sufficient for most deployments under 200 concurrent calls, provided the CRM's disposition endpoint meets the P99 response time and error rate benchmarks. A queuing layer becomes necessary once concurrent call volume during peak launches (500+ simultaneous calls) exceeds what the CRM's database can sustain without lock contention or timeout errors — at that point, the queue decouples AI write speed from CRM write throughput.

It is written to a dead-letter queue and flagged for manual disposition — the engineering team is alerted, and the qualification data (budget, BHK preference, site visit booking, call recording) is preserved outside the CRM until the record can be manually reconciled or the write replayed once the CRM recovers. This prevents permanent loss of a completed qualification call's data.

Disclaimer: Webhook architecture patterns, API design specifications, and security recommendations in this article reflect engineering best practices as of Q2 2026. Implementation complexity, performance characteristics, and DPDP compliance requirements will vary based on your specific CRM architecture, infrastructure stack, and data handling context. Engage a qualified solutions architect and legal counsel before building production PII-handling integrations.

Loading article...

Ready to stop losing leads?

Join 200+ real-estate consultants using Zappio. Go live in 2 hours.

Custom CRM Webhook Architecture for AI Calling — What Real Estate Developers Need to Build

No Pre-Built Connector for Your CRM? Here Is the Webhook Architecture to Build Yourself

The Core Integration Contract: What Both Systems Must Agree On

Part 1 — Lead Push Architecture (CRM → AI Calling Agent)

Part 2 — Pre-Call Status Query (AI Calling Agent → CRM)

Part 3 — Disposition Write-Back (AI Calling Agent → CRM)

Error Handling and Retry Architecture

Security Architecture: PII Protection in Voice AI Integrations

Performance Benchmarks for Custom CRM Endpoints

Frequently Asked Questions

Ready to stop losing leads?

No Pre-Built Connector for Your CRM? Here Is the Webhook Architecture to Build Yourself

The Core Integration Contract: What Both Systems Must Agree On

Part 1 — Lead Push Architecture (CRM → AI Calling Agent)

Part 2 — Pre-Call Status Query (AI Calling Agent → CRM)

Part 3 — Disposition Write-Back (AI Calling Agent → CRM)

Error Handling and Retry Architecture

Security Architecture: PII Protection in Voice AI Integrations

Performance Benchmarks for Custom CRM Endpoints

Frequently Asked Questions