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.

    🖼️ PRINT — Sub-aba Webhooks selecionada, com o botão Novo destacado.

  2. Clique em Novo.

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

  4. Em URL, cole o endereço que vai receber as notificações (começando com https://).

  5. Em Status, deixe em Ativo para começar a enviar imediatamente (ou Inativo para deixar pronto e ligar depois).

  6. Em Eventos, marque quais acontecimentos disparam o envio. Eles estão agrupados:

    • Mensagens: Mensagem recebida, Mensagem enviada, Mensagem atualizada, Mensagem falhou.
  7. Atendimentos: Atendimento criado, Atendimento alterado, Atendimento concluído.
  8. Mensagens: Mensagem recebida, Mensagem enviada, Mensagem atualizada.
Contatos: Contato criado, Contato alterado, Etiqueta alterada.alterada, Contato removido. Cards:Negócios (CRM): CardNegócio criado, CardNegócio alterado, CardNegócio movido de etapa, Anotação criada, Anotação alterada.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).

🖼️ PRINT — Diálogo Novo Webhook com os campos Nome, URL, Status e a lista de Eventos por grupo.

Clique em Criar.

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 6 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, 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, mude o Status para Inativo.

      Erros comuns

      • Sintoma: o botão Criar fica desabilitado. Solução: preencha Nome e URL e marque pelo menos um evento — todos os três são obrigatórios.
      • 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