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.

Lista de webhooks

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.