Webhook para CRM

O Webhook de entrada recebe payloads de CRMs, formulários e automações para criar contatos, mensagens e chats na Underchat. Ele é configurável: primeiro você envia uma amostra, depois mapeia os campos do sistema de origem e só então ativa o fluxo.

POST /v1/webhook/:keyapi HTTP/1.1
Content-Type: application/json

O :keyapi do caminho identifica a configuração e o canal/worker do webhook. Ele é diferente do token enviado no header keyapi das APIs /v1.

Sequência de configuração

1. Abra Integração → Webhooks de entrada.
2. Selecione Novo webhook e informe nome e canal de destino.
3. Copie a URL exclusiva mostrada pela Underchat.
4. Configure seu CRM para enviar um payload representativo.
5. Use Enviar amostra ou dispare um evento real de teste.
6. Em Mapear, associe campos de contato, mensagem e contexto.
7. Revise os dados reconhecidos e marque a integração como Ativa.

Payload de entrada

O webhook não impõe um body universal porque o mapeamento interpreta a estrutura do sistema externo. Um exemplo de amostra seria:

{
  "event": "lead.created",
  "lead": {
    "id": "crm-98321",
    "name": "Maria Silva",
    "phone": "+5561999999999",
    "email": "maria@example.com"
  },
  "message": "Quero falar com o time comercial",
  "campaign": {
    "source": "landing-page",
    "name": "Produto Enterprise"
  }
}

Os nomes acima são ilustrativos. O que importa é que a amostra contenha todos os campos e variações que serão usados no mapeamento.

Campos recomendados na origem

Informação	Por que enviar
ID externo	Correlaciona reenvios e auditoria no CRM.
Nome	Identifica o contato para o atendente.
Telefone com DDI	Permite localizar ou criar o contato no canal correto.
Email/documento	Ajuda a enriquecer e desambiguar contatos.
Texto inicial	Cria contexto para o primeiro atendimento.
Origem/campanha	Pode ser mapeada para contexto, etiqueta ou mensagem.
Data do evento	Facilita auditoria e ordenação de integrações assíncronas.

Envio

curl --request POST \
  --url "https://api.seu-ambiente.com/v1/webhook/CHAVE_EXCLUSIVA_DO_WEBHOOK" \
  --header "Content-Type: application/json" \
  --data @evento-crm.json

Use HTTPS e trate a URL inteira como segredo. Não publique a chave em tickets, prints ou scripts executados no navegador.

Evolução do payload

Quando o CRM mudar sua estrutura:

1. mantenha os campos antigos durante uma janela de transição;
2. envie uma nova amostra;
3. atualize o mapeamento;
4. valide em um contato de teste;
5. ative a nova versão e monitore erros.

Campos ausentes ou em formato diferente podem impedir a identificação do contato ou a criação do chat. Faça validação no sistema de origem e acompanhe as respostas HTTP do webhook.

Webhook ou API pública?

Necessidade	Use
Receber um evento flexível de CRM e mapear campos visualmente	Webhook de entrada
Listar chats ou mensagens existentes	API /v1/chat
Enviar mídia, transferir ou finalizar atendimento	API /v1/chat
Administrar etiquetas e setores	API /v1/label-template e /v1/sector

Os dois recursos podem trabalhar juntos: o webhook inicia o fluxo e a API consulta ou atualiza o atendimento depois.