--- title: "Como conectar um CRM a uma inbox omnichannel com webhooks" description: "Conecte o CRM a uma inbox omnichannel com webhooks: eventos, idempotência, retentativas, correspondência de contatos, privacidade e arquitetura de referência." canonical: "https://omnichannels.ai/pt/blog/connect-crm-omnichannel-inbox-webhooks/" language: "pt" updated: "2026-10-10" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "integration" primaryQuery: "connect crm to omnichannel inbox" keywords: ["integração CRM webhook", "idempotência de webhook", "correspondência de contatos WhatsApp CRM", "API de inbox omnichannel", "verificação de assinatura de webhook", "arquitetura de integração CRM e mensageria"] published: "2026-10-10" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 8 answer: "Para conectar um CRM a uma inbox omnichannel, assine os webhooks da inbox para eventos de conversa e de mensagem. Receba-os em um endpoint enxuto que valida a assinatura e armazena cada evento uma única vez pelo ID do evento. Depois processe de forma assíncrona: associe o remetente a um contato do CRM por telefone normalizado, e-mail ou ID social e grave as atividades de volta. No sentido inverso, use a API da inbox para enviar mensagens ou atualizar responsáveis a partir de fluxos do CRM." takeaways: ["Webhooks enviam eventos da inbox para o CRM quase em tempo real; as APIs buscam dados ou disparam ações no sentido contrário. Uma integração robusta usa as duas.", "A entrega de webhooks costuma ser at-least-once (ao menos uma vez), então o receptor deve deduplicar pelo ID do evento e tolerar eventos fora de ordem.", "Confirme o webhook rapidamente e execute o trabalho no CRM em uma fila em segundo plano, para que chamadas lentas ao CRM não provoquem reenvios e duplicidades.", "Associe contatos por identificadores normalizados, como telefones no formato E.164 e e-mails em minúsculas, e nunca una registros apenas pelo nome.", "Envie somente os dados de que o CRM precisa, mantenha o conteúdo das mensagens fora do CRM quando um resumo bastar e siga a lei de privacidade aplicável, como o GDPR ou as leis de proteção de dados dos Emirados Árabes e da Arábia Saudita."] faq: - q: "Qual é a diferença entre webhook e API na integração com o CRM?" a: "Um webhook é uma requisição HTTP que a inbox envia ao seu endpoint quando algo acontece, como uma nova mensagem ou uma conversa resolvida. Uma API é algo que o seu sistema chama para ler dados ou executar ações, como enviar uma resposta ou reatribuir uma conversa. Os webhooks mantêm o CRM atualizado sem polling; as APIs permitem que fluxos do CRM atuem sobre a inbox." - q: "O que significa idempotência em webhooks?" a: "Idempotência significa que processar o mesmo evento duas vezes tem o mesmo efeito que processá-lo uma vez. Como quem envia webhooks tenta de novo quando não recebe uma resposta de sucesso a tempo, seu endpoint pode receber duplicatas. Guarde o ID único de cada evento, ignore os IDs já processados e faça as gravações no CRM como upserts, para que um evento repetido não crie uma segunda atividade nem um segundo contato." - q: "Como associar um número de WhatsApp a um contato do CRM?" a: "Normalize os dois lados para o formato internacional E.164, com código do país, sem espaços e sem zero à esquerda, e consulte o CRM por esse valor. Se exatamente um contato corresponder, faça o vínculo. Se nenhum corresponder, crie um lead ou um contato não associado. Se vários corresponderem, não adivinhe: sinalize a conversa para que um atendente escolha e registre a decisão para os próximos casos." - q: "As conversas completas devem ser armazenadas no CRM?" a: "Somente se houver finalidade clara e base legal. Muitas equipes guardam no CRM um link para a conversa, um resumo, o resultado e os horários, enquanto a transcrição completa permanece na inbox, com controle de acesso e prazo de retenção próprios. Isso reduz a duplicação de dados pessoais e facilita o atendimento de pedidos de exclusão previstos em leis como o GDPR." - q: "Como proteger endpoints de webhook?" a: "Sirva o endpoint apenas por HTTPS, valide a assinatura ou o segredo compartilhado que o remetente inclui em cada requisição, rejeite requisições com timestamp antigo para limitar ataques de replay e mantenha segredos em um gerenciador de segredos, não no código. Restrinja o que o endpoint pode fazer: ele deve apenas enfileirar eventos, sem expor dados do CRM nem aceitar comandos arbitrários." 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: "Regulamento (UE) 2016/679 (GDPR) — EUR-Lex" url: "https://eur-lex.europa.eu/eli/reg/2016/679/oj" - title: "Leis de proteção de dados — Portal do Governo dos Emirados Árabes Unidos (u.ae)" url: "https://u.ae/en/about-the-uae/digital-uae/data/data-protection-laws" --- # Como conectar um CRM a uma inbox omnichannel com webhooks Canonical: https://omnichannels.ai/pt/blog/connect-crm-omnichannel-inbox-webhooks/ Language: pt Publisher: OmniChannels.ai by BroadNet Technologies Este guia é para CTOs, arquitetos de soluções e administradores de CRM que precisam que o CRM e a inbox omnichannel compartilhem uma única visão do cliente. Ele explica quais eventos sincronizar, como construir um receptor de webhooks que resista a retentativas e duplicatas, como associar contatos entre WhatsApp, Instagram e e-mail e quais regras de privacidade moldam o projeto. ## O que o CRM e a inbox omnichannel devem trocar? A inbox deve informar ao CRM quem entrou em contato, por qual canal, sobre o quê e com que resultado. O CRM deve informar à inbox quem é o cliente, quem é o responsável por ele e que contexto os atendentes precisam ter. | Direção | Dados | Uso típico | |---|---|---| | Inbox para CRM | Nova conversa, canal, identificadores do contato | Criar ou atualizar contato, registrar atividade | | Inbox para CRM | Mudanças de atribuição e de status, resolução | Atualizar a linha do tempo do caso ou da oportunidade, medir tempo de atendimento | | Inbox para CRM | Status de entrega de modelos enviados | Acompanhar resultados de campanhas ou notificações | | CRM para inbox | Nome do contato, idioma, responsável pela conta, nível | Roteamento e personalização | | CRM para inbox | Gatilho para enviar um modelo aprovado | Atualizações de pedido, agendamento ou caso | | CRM para inbox | Mudança de responsável | Direcionar clientes recorrentes ao gerente da conta | Comece com o menor conjunto que sustente um fluxo real. Sincronizar o corpo de todas as mensagens com o CRM raramente é necessário e aumenta a exposição de dados pessoais. ## Quais eventos de webhook assinar? Assine eventos do ciclo de vida, não apenas mensagens. Os nomes exatos variam entre plataformas, então mapeie-os para estas categorias: - **Conversa criada** — primeira mensagem de um cliente em qualquer canal. - **Mensagem recebida** — mensagem de entrada do cliente, com canal e identificador do remetente. - **Mensagem enviada** — mensagem de saída de um atendente ou modelo. - **Status da mensagem** — enviada, entregue, lida ou com falha, quando o canal informa. - **Conversa atribuída** — responsável ou fila alterados. - **Conversa resolvida ou reaberta** — transições de status. - **Contato atualizado** — identificadores ou atributos alterados na inbox. No WhatsApp, os webhooks da própria Meta entregam à plataforma as mensagens recebidas e as atualizações de status das mensagens enviadas; em seguida, o seu provedor de inbox expõe eventos próprios para os seus sistemas. ## Como construir um receptor de webhooks confiável? Aceite rápido, valide, armazene uma vez, processe depois. A maioria dos problemas de entrega vem de executar trabalho do CRM dentro da própria requisição do webhook. ### Projeto do receptor, passo a passo 1. **Exponha um endpoint HTTPS** por ambiente, por exemplo `/webhooks/inbox`. 2. **Verifique a autenticidade.** Confira a assinatura (em geral um HMAC do corpo bruto com um segredo compartilhado, conforme a RFC 2104) ou o token documentado pelo remetente. Calcule-a sobre os bytes brutos antes de interpretar o JSON. 3. **Verifique a atualidade.** Se houver timestamp, rejeite eventos fora de uma tolerância curta para limitar replays. 4. **Deduplique.** Insira o ID do evento em uma tabela com restrição de unicidade. Se a inserção falhar porque o ID já existe, retorne sucesso e pare. 5. **Enfileire.** Coloque o evento em uma fila e retorne imediatamente uma resposta 2xx. 6. **Processe de forma assíncrona.** Um worker lê a fila, associa o contato e grava no CRM com upserts. 7. **Tente de novo com backoff.** Se o CRM estiver fora do ar, repita a partir da sua fila com backoff exponencial; não dependa das retentativas do remetente. 8. **Use uma dead-letter queue.** Após várias falhas, mova o evento para ela e avise uma pessoa. 9. **Reconcilie.** Rode periodicamente um job que compara conversas recentes da inbox com os registros do CRM e preenche lacunas pela API da inbox. ### Por que idempotência e ordem importam Quem envia webhooks costuma tentar de novo quando não recebe uma resposta de sucesso a tempo, o que torna a entrega at-least-once. O mesmo evento pode chegar duas vezes, e um evento "resolvida" pode chegar antes da última "mensagem recebida". Lide com isso assim: - Use o ID do evento como chave de deduplicação. - Use upserts baseados no ID da conversa ou da mensagem no CRM. - Compare timestamps ou números de sequência e ignore estados mais antigos. Quando o fluxo do CRM chamar a API da inbox para enviar uma mensagem, passe uma chave de idempotência se a API a aceitar; o rascunho do IETF para o cabeçalho HTTP `Idempotency-Key` descreve o padrão mais comum. ## Como associar contatos entre canais? Associe por identificadores normalizados, prefira correspondências determinísticas e encaminhe ambiguidades a uma pessoa. | Identificador | Normalizar como | Confiança da correspondência | Observações | |---|---|---|---| | Telefone de WhatsApp ou SMS | E.164, por exemplo +9715XXXXXXXX | Alta | Atenção a formatos locais com zero à esquerda | | Endereço de e-mail | Minúsculas, sem espaços | Alta | Aliases podem ser a mesma pessoa; não presuma | | Conta do Instagram | ID de usuário da plataforma | Alta dentro dessa conta | Handles podem mudar; guarde o ID, não só o handle | | Usuário do Telegram | ID de usuário da plataforma | Alta dentro desse bot ou conta | O telefone pode não ser compartilhado | | Nome | Nunca usar isoladamente | Baixa | Jamais una registros pelo nome | Regras de decisão: 1. Uma correspondência exata: vincular. 2. Nenhuma correspondência: criar um lead ou "contato não associado" com o canal de origem. 3. Várias correspondências: sinalizar para um atendente, sem unir automaticamente. 4. O cliente confirma outro identificador na conversa: vincular e anotar a evidência. ## Como tratar a privacidade de dados em uma integração com o CRM? Mova apenas o que cada sistema precisa, documente o motivo e faça a exclusão funcionar nos dois sistemas. - **Minimização de dados.** Guarde no CRM links de conversas, resultados e resumos; mantenha as transcrições completas na inbox, salvo finalidade definida. - **Base legal e consentimento.** Registre o opt-in de marketing por canal; uma conversa de suporte não é consentimento para modelos de marketing. - **Retenção.** Alinhe os prazos de retenção na inbox, no CRM, nas filas e nos logs; logs de payloads de webhook costumam ser esquecidos. - **Controle de acesso.** Limite quem pode ver o conteúdo e os anexos das mensagens no CRM. - **Pedidos de exclusão e de acesso.** Faça com que um pedido feito em um sistema se propague ao outro. - **Transferências internacionais.** Verifique onde cada sistema armazena os dados. O GDPR se aplica aos dados pessoais de pessoas na UE, e os Emirados Árabes e a Arábia Saudita têm leis próprias de proteção de dados pessoais; confirme as obrigações vigentes com o órgão regulador competente e com seu jurídico. ## Como é uma arquitetura de referência? Em texto, o fluxo é: canais para a inbox, inbox para o receptor, receptor para a fila, fila para o worker, worker para o CRM e fluxos do CRM de volta para a API da inbox. | Componente | Responsabilidade | Decisão de projeto principal | |---|---|---| | Canais (WhatsApp, Instagram, e-mail, Telegram) | Entregar mensagens de clientes à inbox | Regidos pelas regras de cada plataforma | | Inbox omnichannel | Conversas, atribuição, atendentes, eventos | Emite webhooks; expõe API | | Receptor de webhooks | Validar, deduplicar, enfileirar | Sem estado, resposta 2xx rápida | | Armazenamento de eventos e fila | Buffer durável, replay | ID de evento único, dead-letter queue | | Worker de sincronização | Associação de contatos, upserts no CRM | Gravações idempotentes, backoff | | CRM | Contatos, oportunidades, casos, fluxos | Chama a API da inbox com chaves de idempotência | | Job de reconciliação | Detectar e reparar lacunas | Executa em agenda | | Monitoramento | Atraso, falhas, dead letters | Alertas para um responsável | ## Exemplo prático: um grupo de clínicas em Jeddah A "Wahat Clinics", um grupo de saúde fictício na Arábia Saudita, usa um CRM para consultas dos pacientes e uma inbox para WhatsApp e e-mail. - Um paciente envia mensagem pelo WhatsApp. A inbox emite um evento de conversa criada; o receptor valida, armazena e enfileira. - O worker normaliza o número para E.164, encontra um único cadastro de paciente e registra uma atividade com o link da conversa, não com o texto da mensagem. - O CRM mostra o árabe como idioma preferido do paciente e o envia à inbox, que o direciona para a fila em árabe. - Quando a consulta é agendada no CRM, um fluxo chama a API da inbox para enviar a confirmação como modelo utility aprovado, passando o ID da consulta como chave de idempotência para que uma retentativa não envie duas confirmações. - O evento "mensagem entregue" da inbox atualiza o registro da consulta. ## Quais são os erros mais comuns? - **Gravar no CRM dentro da requisição do webhook**, causando timeouts, retentativas e duplicatas. - **Não deduplicar**, criando atividades e contatos duplicados. - **Associar por telefones não normalizados**, de modo que os formatos com +971 e com 0 nunca se encontram. - **Unir automaticamente por nome ou correspondências parciais.** - **Copiar todo o conteúdo das mensagens para o CRM** sem finalidade nem regra de retenção. - **Não reconciliar**, fazendo de um evento perdido uma divergência permanente. - **Segredos no código-fonte** e nenhum plano de rotação. ## Como a OmniChannels.ai ajuda A OmniChannels.ai, com tecnologia da BroadNet Technologies, reúne as conversas de WhatsApp, Instagram, Messenger, Telegram e e-mail em um único [Omni Inbox](/pt/platform/unified-inbox/), com atribuição de atendentes e tags, além da ativação do WhatsApp pelo Embedded Signup da Meta e de modelos aprovados com variáveis, mídia e botões. Para a integração com o CRM, a [API REST](/developers/) tem documentação pública com especificação OpenAPI 3.1, e os [webhooks](/developers/webhooks/) informam os status de entrega (SENT, DELIVERED, READ, FAILED e outros) em um formato normalizado único. Relatórios de entrega com filtros e exportação em CSV facilitam a conciliação. Comece pela página de [desenvolvedores](/developers/).