Webhooks: receba os eventos da conta em outro sistema
🔒 Disponível para administradores.
Um webhook é um endereço (URL) do seu sistema — CRM, ERP, n8n, Make, um script próprio — que a plataforma chama, com uma requisição POST em JSON, toda vez que acontece um evento na sua conta: uma mensagem chegou, uma conversa foi resolvida, um contato foi criado. É a forma mais simples de integrar a plataforma a outras ferramentas sem consultar a API o tempo todo.
Criar um webhook
Vá em Configurações → Integrações → Webhooks e clique em Configurar. A lista mostra cada webhook com os eventos assinados, a chave para ativar ou desativar, e o motivo quando ele foi desativado sozinho.
Clique em Adicionar novo Webhook. O assistente tem quatro etapas:
Nome e descrição — para identificar o webhook na lista (por exemplo, CRM — novos contatos).
URL de destino — o endereço que vai receber as requisições. Precisa ser https:// e responder em poucos segundos.
Eventos — marque só os eventos de que o sistema precisa; cada um gera uma requisição. O código ao lado de cada evento é o valor do campo event no JSON.
Cabeçalhos, autenticação e extra — opcional, veja abaixo. Clique em Criar webhook.
Uma conta pode ter vários webhooks, cada um com os próprios eventos.
Eventos disponíveis
Seção
Evento
Quando dispara
Conversas
Conversa Criada
Uma conversa nova é aberta em qualquer caixa
Conversa Atualizada
Mudou responsável, equipe, etiquetas, prioridade ou atributos (traz o que mudou)
Status da Conversa Alterado
Aberta, pendente, adiada ou resolvida
Digitação na conversa ativada / desativada
O contato começou ou parou de digitar (chat do site)
Mensagens
Mensagem criada
Toda mensagem, recebida ou enviada (inclui notas privadas, marcadas como tal)
Mensagem atualizada
Status de entrega/leitura ou conteúdo alterado
Contatos
Contato criado / Contato atualizado
Cadastro novo ou alteração de nome, telefone, e-mail, atributos
Inbox
Inbox criado / atualizado / excluído
Mudanças nas caixas de entrada
Widget de Chat ao Vivo
Widget de chat ao vivo aberto pelo usuário
O visitante abriu o chat do site
Kanban
Card do Kanban criado / atualizado / mudou de etapa
Movimentação nos quadros — veja Kanban
Importações
Importação concluída / Importação falhou
Fim de uma importação de contatos
O que chega no seu sistema
Cada requisição traz o campo event com o nome do evento e os dados do objeto envolvido. Exemplo simplificado de uma mensagem recebida:
{
"event": "message_created",
"id": 1521,
"content": "Oi, quero saber o prazo de entrega",
"message_type": "incoming",
"private": false,
"created_at": "2026-10-09T14:21:07.000Z",
"sender": {
"id": 87,
"name": "João Pereira",
"phone_number": "+5511999990000"
},
"conversation": {
"id": 342,
"status": "open",
"assignee_id": 5,
"labels": ["suporte"]
},
"inbox": { "id": 4, "name": "WhatsApp Oficial" },
"account": { "id": 1, "name": "Loja Exemplo" }
}
Os eventos de conversa trazem a conversa completa (contato, responsável, equipe, etiquetas, atributos personalizados e as últimas mensagens); Conversa Atualizada inclui changed_attributes com o valor anterior e o atual de cada campo alterado.
Cabeçalhos, autenticação, parâmetros e payload extra
Na última etapa (e na edição), as abas avançadas servem para o seu sistema reconhecer e autenticar as chamadas:
Cabeçalhos — cabeçalhos HTTP enviados em toda requisição (por exemplo, X-Origem: chat).
Autenticação — Basic Auth (usuário e senha), Bearer Token ou API Key em um cabeçalho com o nome que você escolher.
Parâmetros de URL — acrescentados à URL de destino (?origem=chat).
Payload Extra — campos adicionais mesclados ao JSON, úteis para identificar a conta ou o ambiente no destino.
Nos valores, use variáveis entre chaves duplas, resolvidas na hora do envio: {{account.id}}, {{account.name}}, {{conversation.id}}, {{conversation.status}}, {{contact.id}}, {{contact.name}}, {{contact.email}}, {{contact.phone_number}}, {{message.id}}, {{message.content}}, {{inbox.id}}, {{inbox.name}} e {{event}}.
Ativar, desativar e falhas de entrega
A chave na lista ativa ou desativa um webhook sem excluí-lo.
Se o destino não responder (erro ou tempo esgotado) várias vezes seguidas, o webhook é desativado automaticamente e a lista mostra o motivo (Desativado automaticamente após N falhas consecutivas de entrega). Corrija o destino e ligue a chave de novo: o contador de falhas zera.
Um webhook com o selo Sistema foi criado pela instalação para uma integração da plataforma; não pode ser editado nem excluído por aqui.
Criar, editar e excluir webhooks ficam nos Registros de auditoria.
Webhook ou automação?
Webhook — manda todo evento de um tipo, sem condições. Ideal para sincronizar um CRM ou alimentar um relatório externo.
Ação "Enviar evento de webhook" de uma automação ou macro — manda a conversa para uma URL só quando as condições da regra são atendidas (uma etiqueta específica, uma caixa, uma palavra na mensagem). Ideal para acionar um fluxo pontual.
Para mostrar o seu sistema dentro da plataforma, em vez de só receber eventos dele, veja Apps da Dashboard.
💡 A API completa da plataforma (criar contatos, enviar mensagens, consultar conversas) usa o token de acesso do seu perfil — veja a aba Segurança e acesso em Perfil. Prefira um usuário dedicado às integrações, e nunca o desative.