Skip to main content

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

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

Ajustes → Integrações na sub-aba Webhooks, com o botão Novo em destaque
Ajustes → Integrações na sub-aba Webhooks, com o botão Novo em destaque

  1. Clique em Novo.

  2. Em Nome, dê um nome ao webhook (ex.: Notificação N8N).

  3. Em URL, cole o endereço que vai receber as notificações (começando com https:// — só aceitamos URL https pública).

  4. (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.

  5. 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.

  6. 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
Janela Novo webhook preenchida: Nome, URL, Segredo, Formato do payload, o interruptor Ativo e três eventos marcados na lista
  1. 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, Pipeline (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.

Artigos relacionados