--- title: "How to Connect a CRM to an Omnichannel Inbox With Webhooks" description: "Connect a CRM to an omnichannel inbox with webhooks: which events to sync, idempotency, retries, contact matching, data privacy and a reference architecture." canonical: "https://omnichannels.ai/blog/connect-crm-omnichannel-inbox-webhooks/" language: "en" updated: "2026-10-10" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "integration" primaryQuery: "connect crm to omnichannel inbox" keywords: ["crm webhook integration", "webhook idempotency", "contact matching whatsapp crm", "omnichannel inbox api", "webhook signature verification", "crm messaging integration architecture"] published: "2026-10-10" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 8 answer: "To connect a CRM to an omnichannel inbox, subscribe to inbox webhooks for conversation and message events, receive them on a small endpoint that verifies signatures and stores each event once using its event ID, then process them asynchronously: match the sender to a CRM contact by normalised phone, email or social ID, and write activities back. Use the inbox API in the other direction to send messages or update ownership from CRM workflows." takeaways: ["Webhooks push events from the inbox to the CRM in near real time; APIs pull data or trigger actions in the other direction. A robust integration uses both.", "Webhook delivery is usually at-least-once, so the receiver must deduplicate by event ID and tolerate events arriving out of order.", "Acknowledge webhooks quickly and do the CRM work in a background queue, so slow CRM calls do not trigger retries and duplicates.", "Match contacts on normalised identifiers such as E.164 phone numbers and lowercase email addresses, and never merge records on a name alone.", "Send only the data the CRM needs, keep message content out of the CRM where a summary is enough, and follow the privacy law that applies, such as GDPR or the UAE and Saudi data protection laws."] faq: - q: "What is the difference between a webhook and an API for CRM integration?" a: "A webhook is an HTTP request the inbox sends to your endpoint when something happens, such as a new message or a conversation being resolved. An API is something your system calls to read data or perform actions, such as sending a reply or reassigning a conversation. Webhooks keep the CRM current without polling; APIs let CRM workflows act on the inbox." - q: "What does idempotency mean for webhooks?" a: "Idempotency means processing the same event twice has the same effect as processing it once. Because webhook senders retry when they do not get a timely success response, your endpoint can receive duplicates. Store each event's unique ID, skip IDs you have already processed, and design CRM writes as upserts so a repeated event cannot create a second activity or contact." - q: "How do you match a WhatsApp number to a CRM contact?" a: "Normalise both sides to the international E.164 format, including country code and no spaces or leading zeros, then look up the CRM by that value. If exactly one contact matches, link it. If none match, create a lead or an unmatched contact. If several match, do not guess; flag the conversation for an agent to choose, and record the decision for next time." - q: "Should full chat transcripts be stored in the CRM?" a: "Only if you have a clear purpose and legal basis. Many teams store a link to the conversation, a summary, the outcome and timestamps in the CRM, while the full transcript stays in the inbox with its own access controls and retention period. This reduces duplicated personal data and makes deletion requests easier to fulfil under laws such as GDPR." - q: "How should webhook endpoints be secured?" a: "Serve the endpoint over HTTPS only, verify the signature or shared secret the sender includes with each request, reject requests with old timestamps to limit replay, and keep secrets in a secrets manager rather than code. Restrict what the endpoint can do: it should only queue events, not expose CRM data or accept arbitrary commands." sources: - title: "Webhooks — WhatsApp Cloud API, Meta for Developers" url: "https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks" - title: "The Idempotency-Key HTTP Header Field — IETF HTTPAPI Working Group draft" url: "https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/" - title: "RFC 2104: HMAC — Keyed-Hashing for Message Authentication" url: "https://www.rfc-editor.org/rfc/rfc2104" - title: "Regulation (EU) 2016/679 (GDPR) — EUR-Lex" url: "https://eur-lex.europa.eu/eli/reg/2016/679/oj" - title: "Data protection laws — The UAE Government portal (u.ae)" url: "https://u.ae/en/about-the-uae/digital-uae/data/data-protection-laws" --- # How to Connect a CRM to an Omnichannel Inbox With Webhooks Canonical: https://omnichannels.ai/blog/connect-crm-omnichannel-inbox-webhooks/ Language: en Publisher: OmniChannels.ai by BroadNet Technologies This guide is for CTOs, solution architects and CRM administrators who need their CRM and their omnichannel inbox to share one view of the customer. It explains which events to sync, how to build a webhook receiver that survives retries and duplicates, how to match contacts across WhatsApp, Instagram and email, and what privacy rules shape the design. ## What should a CRM and an omnichannel inbox exchange? The inbox should tell the CRM who contacted you, on which channel, about what, and with what outcome. The CRM should tell the inbox who the customer is, who owns them and what context agents need. | Direction | Data | Typical use | |---|---|---| | Inbox to CRM | New conversation, channel, contact identifiers | Create or update contact, log activity | | Inbox to CRM | Assignment and status changes, resolution | Update case or deal timeline, report handling time | | Inbox to CRM | Message delivery status for outbound templates | Track campaign or notification outcomes | | CRM to inbox | Contact name, language, account owner, tier | Routing and personalisation | | CRM to inbox | Trigger to send an approved template | Order, appointment or case updates | | CRM to inbox | Ownership change | Route returning customers to their account manager | Start with the smallest set that supports a real workflow. Syncing every message body into the CRM is rarely needed and increases privacy exposure. ## Which webhook events should you subscribe to? Subscribe to lifecycle events, not just messages. Exact event names differ between platforms, so map them to these categories: - **Conversation created** — first message from a customer on any channel. - **Message received** — inbound customer message, with channel and sender identifier. - **Message sent** — outbound agent or template message. - **Message status** — sent, delivered, read or failed, where the channel reports it. - **Conversation assigned** — owner or queue changed. - **Conversation resolved or reopened** — status transitions. - **Contact updated** — identifiers or attributes changed in the inbox. For WhatsApp, Meta's own webhooks deliver inbound messages and status updates for outbound messages to the platform; your inbox provider then exposes its own events to your systems. ## How do you build a reliable webhook receiver? Accept fast, verify, store once, process later. Most delivery problems come from doing CRM work inside the webhook request. ### Step-by-step receiver design 1. **Expose one HTTPS endpoint** per environment, for example `/webhooks/inbox`. 2. **Verify authenticity.** Check the signature (commonly an HMAC of the raw body with a shared secret, as defined in RFC 2104) or the token the sender documents. Compute it on the raw bytes before parsing JSON. 3. **Check freshness.** If a timestamp is included, reject events outside a short tolerance to limit replays. 4. **Deduplicate.** Insert the event ID into a table with a unique constraint. If the insert fails because the ID exists, return success and stop. 5. **Enqueue.** Put the event on a queue and return a 2xx response immediately. 6. **Process asynchronously.** A worker reads the queue, matches the contact, and writes to the CRM using upserts. 7. **Retry with backoff.** If the CRM is down, retry from your queue with exponential backoff; do not rely on the sender's retries. 8. **Dead-letter.** After several failures, move the event to a dead-letter queue and alert a person. 9. **Reconcile.** Run a periodic job that compares recent inbox conversations with CRM records and fills gaps from the inbox API. ### Why idempotency and ordering matter Webhook senders typically retry when they do not get a timely success response, which makes delivery at-least-once. The same event can arrive twice, and a "resolved" event can arrive before the last "message received". Handle this by: - Using the event ID as the deduplication key. - Using upserts keyed on the conversation or message ID in the CRM. - Comparing event timestamps or sequence numbers and ignoring older state. When your CRM workflow calls the inbox API to send a message, pass an idempotency key if the API supports one; the IETF draft for an `Idempotency-Key` HTTP header describes the common pattern. ## How should contacts be matched across channels? Match on normalised identifiers, prefer deterministic matches, and route ambiguity to a person. | Identifier | Normalise as | Match confidence | Notes | |---|---|---|---| | WhatsApp or SMS phone number | E.164, for example +9715XXXXXXXX | High | Watch for local formats with leading zero | | Email address | Lowercase, trimmed | High | Aliases may be the same person; do not assume | | Instagram account | Platform-scoped user ID | High within that account | Handles can change; store the ID, not only the handle | | Telegram user | Platform user ID | High within that bot or account | Phone may not be shared | | Name | Not used alone | Low | Never merge on name | Decision rules: 1. One exact match: link. 2. No match: create a lead or "unmatched contact" with the source channel. 3. Multiple matches: flag for an agent, do not auto-merge. 4. Customer confirms another identifier in conversation: link it with a note of the evidence. ## How do you handle data privacy in a CRM integration? Move only what each system needs, document why, and make deletion work across both systems. - **Data minimisation.** Store conversation links, outcomes and summaries in the CRM; keep full transcripts in the inbox unless there is a defined purpose. - **Lawful basis and consent.** Record marketing opt-in per channel; a support conversation is not consent for marketing templates. - **Retention.** Align retention periods in the inbox, CRM, queues and logs; webhook payload logs are often forgotten. - **Access control.** Limit who can see message content and attachments in the CRM. - **Deletion and access requests.** Make a request in one system propagate to the other. - **Cross-border transfers.** Check where each system stores data. GDPR applies to personal data of people in the EU, and the UAE and Saudi Arabia have their own personal data protection laws; confirm current obligations with the relevant regulator and your legal team. ## What does a reference architecture look like? In text form, the flow is: channels to inbox, inbox to receiver, receiver to queue, queue to worker, worker to CRM, and CRM workflows back to the inbox API. | Component | Responsibility | Key design choice | |---|---|---| | Channels (WhatsApp, Instagram, email, Telegram) | Deliver customer messages to the inbox | Governed by each platform's rules | | Omnichannel inbox | Conversations, assignment, agents, events | Emits webhooks; exposes API | | Webhook receiver | Verify, deduplicate, enqueue | Stateless, fast 2xx response | | Event store and queue | Durable buffer, replay | Unique event ID, dead-letter queue | | Sync worker | Contact matching, CRM upserts | Idempotent writes, backoff | | CRM | Contacts, deals, cases, workflows | Calls inbox API with idempotency keys | | Reconciliation job | Detect and repair gaps | Runs on a schedule | | Monitoring | Lag, failures, dead letters | Alerts to an owner | ## Worked example: a Jeddah clinic group "Wahat Clinics", a synthetic healthcare group in Saudi Arabia, uses a CRM for patient appointments and an inbox for WhatsApp and email. - A patient messages on WhatsApp. The inbox emits a conversation created event; the receiver verifies, stores and queues it. - The worker normalises the number to E.164, finds one patient record, and logs an activity with a link to the conversation, not the message text. - The CRM shows the patient's preferred language as Arabic and pushes it to the inbox, which routes to the Arabic queue. - When the appointment is booked in the CRM, a workflow calls the inbox API to send an approved utility template confirmation, passing the appointment ID as the idempotency key so a retry cannot send two confirmations. - The inbox's "message delivered" event updates the appointment record. ## What are the common mistakes? - **Doing CRM writes inside the webhook request**, causing timeouts, retries and duplicates. - **No deduplication**, creating duplicate activities and contacts. - **Matching on unnormalised phone numbers**, so +971 and 0 formats never meet. - **Auto-merging on name or partial matches.** - **Copying all message content into the CRM** without a purpose or retention rule. - **No reconciliation**, so a missed event becomes permanent drift. - **Secrets in source code**, and no rotation plan. ## How OmniChannels.ai helps OmniChannels.ai, powered by BroadNet Technologies, brings WhatsApp, Instagram, Messenger, Telegram and Email conversations into one [Omni Inbox](/platform/unified-inbox/) with agent assignment and tagging, plus WhatsApp onboarding through Meta Embedded Signup and approved templates with variables, media and buttons. For CRM integration, the [REST API](/developers/) is publicly documented with an OpenAPI 3.1 spec, and [webhooks](/developers/webhooks/) report delivery statuses (SENT, DELIVERED, READ, FAILED and more) in one normalised format. Delivery reports with filters and CSV export support reconciliation. Start on the [developers](/developers/) page.