Webhooks
O webhook da conta manda um aviso para uma URL sua sempre que acontece um evento escolhido.
Fica em Config. → Integrações → Webhooks. Criar e editar exige ser administrador.
A tela de integrações também abre para quem tem a permissão de gerenciar integrações. Salvar webhook é só para administrador.

- Adicionar novo Webhook.
- Preencha a URL do Webhook que vai receber e dê um nome (o campo aparece em inglês, Webhook Name).
- Marque os Eventos.
- Criar webhook.
A URL precisa ser pública, com http ou https. Endereço de rede interna é recusado na hora de salvar, por segurança. Se você quer entregar num sistema que está na sua rede, exponha um endereço público ou use um túnel.
Os eventos
Seção intitulada “Os eventos”Na tela aparecem dez:
Conversa criada · Conversa atualizada · Status de conversa alterado · Mensagem criada · Mensagem atualizada · Widget de chat aberto pelo usuário · Contato criado · Contato atualizado · Status de digitação ativado · Status de digitação desativado
Existem outros três, que se assinam pela API: caixa criada, caixa atualizada e evento de conversão registrado.
O último é o mais útil dos três: ele dispara quando entra uma conversão, com os dados do contato, o identificador da conversão e as propriedades do evento.
O formato
Seção intitulada “O formato”Uma chamada POST com corpo em JSON. O conteúdo é o dado da entidade mais o campo event com o nome do evento. Eventos de atualização trazem também o que mudou.
Dois limites que mudam o seu projeto
Seção intitulada “Dois limites que mudam o seu projeto”Não existe assinatura. A chamada sai sem cabeçalho de segredo e sem HMAC, então quem recebe não tem como provar que veio do CRM.
O contorno é simples e é o que recomendamos: coloque um segredo na própria URL, do tipo https://seu-sistema.com/hooks/smart2?k=UM_SEGREDO_LONGO, e valide do outro lado.
Não existe reentrega. Se o seu endereço estiver fora do ar ou demorar demais, aquele evento se perde. Não há nova tentativa, não há fila de falhas e não há tela de entregas.
Consequência prática: para coisa crítica, não dependa só do webhook. Combine com uma consulta periódica pela API, ou use o gatilho de webhook do fluxo, que tem resposta e registro de execução.
Quando um evento não dispara
Seção intitulada “Quando um evento não dispara”- Contato atualizado e caixa atualizada só disparam quando algum campo mudou de verdade.
- Mensagem criada e mensagem atualizada não disparam para todo tipo de mensagem interna.
- O tempo de espera padrão da chamada é curto. Endpoint lento perde o evento.
Alternativas dentro do fluxo
Seção intitulada “Alternativas dentro do fluxo”Muitas vezes o que você quer não é o webhook da conta, e sim uma ação dentro de um fluxo:
| Você quer | Use |
|---|---|
| Avisar um sistema quando algo acontece, sem esperar resposta | Ação Enviar webhook |
| Consultar um sistema e usar a resposta nos próximos passos | Ação Consultar API |
| Disparar um evento só em certas condições | Fluxo com condição, em vez do webhook da conta |
A vantagem do fluxo é ter condição, espera e o registro de cada execução, com o que entrou e o que voltou.