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 → Integrações → Webhooks

Passo a passo

Abra Ajustes → Integrações e fique na sub-aba Webhooks.

Ajustes → Integrações na sub-aba 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 → Auditoria.