Como conectar um CRM a uma inbox omnichannel com webhooks

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.

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.

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.

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, 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 tem documentação pública com especificação OpenAPI 3.1, e os 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.