Configurar webhooks para sistemas externos

Um webhook faz o AtendeBot avisar um sistema externo toda vez que algo acontece: uma mensagem recebida, um atendimento concluído, um card movido de etapa. Você informa uma URL e escolhe os eventos, e o AtendeBot envia os dados para lá automaticamente.
Objetivo
Cadastrar um webhook para que sistemas externos recebam notificações de eventos da sua conta.
Pré-requisitos
Perfil Administrador.
Uma URL pública pronta para receber os dados (ex.: um fluxo no n8n, Zapier ou um endpoint do seu sistema).
Tempo estimado
5 minutos.
Caminho de acesso
Ajustes → API e webhooks → Webhooks
Passo a passo
Abra Ajustes → API e webhooks (grupo Integrações) e clique na visão Webhooks.
Ajustes → API e webhooks na visão Webhooks, com o botão Novo em destaque
Clique em Novo.
Em Nome, dê um nome ao webhook (ex.: 
Notificação N8N).
Em URL, cole o endereço que vai receber as notificações (começando com 
https://; só aceitamos URL https pública).
(Opcional) Em Segredo, cole uma chave própria para o AtendeBot assinar cada entrega com HMAC SHA-256 no cabeçalho 
X-Atendebot-Signature. Depois de salvo, o campo não é exibido de novo.
No topo do diálogo, o interruptor Ativo já vem ligado: deixe assim para começar a enviar imediatamente, ou desligue para deixar o webhook pronto e ativar depois.
Em Eventos, marque quais acontecimentos disparam o envio. Eles estão agrupados:
Mensagens: Mensagem recebida, Mensagem enviada, Mensagem atualizada, Mensagem falhou.
Atendimentos: Atendimento criado, Atendimento alterado, Atendimento concluído.
Contatos: Contato criado, Contato alterado, Etiqueta alterada, Contato removido.
Negócios (CRM): Negócio criado, Negócio alterado, Negócio movido de etapa, Anotação criada, Anotação alterada, Campo personalizado alterado, Empresa do negócio alterada, Negócio ganho, Negócio perdido, Negócio removido, Proposta enviada, Lead capturado.
Tarefas: Tarefa criada, Tarefa concluída.
Pesquisas de satisfação: Pesquisa respondida.
Agentes: Agente movido de equipe.
O botão 
{ } ao lado de cada evento marcado abre um exemplo do envelope no formato de payload escolhido (veja Formato do payload, abaixo).
Janela Novo webhook preenchida: Nome, URL, Segredo, Formato do payload, o interruptor Ativo e três eventos marcados na lista
Clique em Criar webhook.
Formato do payload
No diálogo de criar/editar, o campo Formato do payload escolhe entre:
v2 (legado): o corpo chega em 
payload, com campos terminados em 
_id (
contact_id, 
card_id...). Está descontinuado: não recebe novidades, e o escopo por evento (abaixo) não existe nele.
v3 (recomendado, padrão nos webhooks novos): o corpo chega em 
data, com objetos completos em vez de 
_id (
contact: { id, name, ... }). Nos eventos de mudança (ex.: Atendimento alterado, Negócio movido de etapa), 
data também traz 
changed (os campos que mudaram) e 
previous, com o valor de cada um antes da mudança.
O botão 
{ } do passo 7 mostra o exemplo já neste formato.
Escopo por evento
Disponível só no formato v3. Quando um evento está marcado, aparece ao lado do 
{ } um ícone de funil: ele abre um painel para restringir QUANDO aquele evento é entregue: por exemplo, só mensagens de um canal, ou só cards de um responsável.
Os critérios variam por evento e podem incluir canal, equipe, responsável, status do atendimento, remetente da mensagem, Funil (no evento Lead capturado), etapa, etiqueta e campo personalizado; e, nos eventos que carregam o valor anterior, também a transição ("saiu de"/"entrou em") de responsável, equipe, status ou etapa.
Todos os critérios marcados precisam casar; dentro de um mesmo critério, basta um valor bater. Ex.: canal = WhatsApp Oficial e (responsável = Ana ou responsável = Bruno).
"Sem responsável" é uma opção própria do critério de responsável, para casar atendimentos ou cards ainda sem ninguém atribuído.
Evento sem o contexto que o critério pede é descartado, não entregue sem filtro: uma pesquisa de satisfação sem atendimento vinculado ou uma tarefa sem card, por exemplo.
Aplicar a todos os eventos compatíveis copia o escopo montado para os outros eventos marcados que aceitam os mesmos critérios.
Trocar o formato para v2 remove o escopo salvo: o diálogo pede confirmação antes de apagar.
A chamada de teste de entrega da API ignora o escopo: o exemplo sempre chega, mesmo que não passasse pelo filtro salvo.
Canal, equipe ou outro recurso apagado depois de escolhido no critério fica sem efeito até você reabrir o webhook: o painel avisa que o valor não existe mais nesta conta e oferece removê-lo.
Resultado esperado
O webhook aparece na lista com o nome, a marca ATIVO, a URL e as etiquetas dos eventos escolhidos. A partir daí, cada evento marcado envia uma notificação para a sua URL. Para ajustar depois, clique no ícone de lápis e altere; para desligar sem apagar, edite o webhook e desligue o interruptor Ativo.
Erros comuns
Sintoma: cliquei em Criar webhook e nada aconteceu. Solução: preencha Nome e URL e marque pelo menos um evento: o diálogo mostra a mensagem de erro embaixo de cada campo vazio (o botão continua clicável, mas o webhook só é criado depois de corrigir todos).
Sintoma: o sistema externo não recebe nada. Solução: confira se o webhook está ATIVO, se a URL está correta e acessível publicamente, e se os eventos certos foram marcados. O histórico de disparos fica em Ajustes → API e webhooks → Registro.
Artigos relacionados
Gerar tokens de API para integrações
Criar sua primeira automação
Concluir e classificar um atendimento