Webhook e N8N

🌐 WebHook - Visão Geral

O sistema NextChat oferece suporte a WebHooks de duas maneiras principais, configuradas em um único lugar:

Na tela, há duas abas:

• 🧩 Integrações por Canal — o webhook é aplicado a todos os atendimentos de um canal (ex.: um número de WhatsApp conectado).
• ⚙️ Integrações por Fila — o webhook é aplicado somente aos atendimentos de uma fila (integrações do tipo N8N).

🧩 1. Pela Fila (Integrações por Fila)

Caminho: Configurações → Automação e Integrações → Webhooks → aba Integrações por Fila

1. Clique em Nova Integração N8N.
2. Preencha os campos:
   • Nome da integração (obrigatório — serve para você identificar)
   • URL do Webhook/N8N (obrigatória — é para onde o NextChat fará o POST)
   • Eventos — marque quais eventos deseja receber
3. (Opcional) Em Mostrar configurações avançadas, informe o Bearer Token / API Key.
4. Clique em Testar integração para confirmar que a URL responde.
5. Clique em Salvar.
6. Na lista, clique no botão foguete (Vincular à fila). O assistente vai:
   • procurar uma fila já vinculada a essa integração ou criar uma nova fila com o mesmo nome da integração;
   • vincular a integração à fila, deixando-a ativa automaticamente (a opção “Inicia Integração ao transferir” já vem marcada para integrações N8N);
   • (opcional) permitir escolher os canais que serão associados a essa fila.

Quando os eventos são enviados?

• Quando um ticket é transferido para a fila vinculada, a integração é ativada para aquele ticket;
• Se “Inicia Integração ao transferir” estiver marcado, a integração dispara imediatamente ao transferir (usando a última mensagem recebida);
• A partir daí, cada nova mensagem (recebida ou enviada) daquele ticket dispara o webhook, respeitando os eventos marcados.

🔧 2. Pelo Canal (Integrações por Canal)

Caminho: Configurações → Automação e Integrações → Webhooks → aba Integrações por Canal

1. A aba lista os canais disponíveis (WhatsApp, WhatsApp Oficial, etc. — os canais de E-mail e SMS não aparecem, pois não usam webhook por canal).
2. Clique em Configurar no canal desejado.
3. Ative o interruptor Integração Ativada.
4. Informe a URL do Webhook/N8N (obrigatória — endereço que receberá os eventos).
5. Marque os Eventos desejados.
   • Caso nenhum evento esteja marcado, nenhuma requisição será enviada.
6. (Opcional) Em Mostrar configurações avançadas, informe o Bearer Token / API Key — usado para validar a origem do webhook no destino.
7. Clique em Testar integração e depois em Salvar.

📋 Campos da tela (explicados um a um)

Na aba Integrações por Canal

Na aba Integrações por Fila

Na lista de integrações por fila também existem os botões de ação em cada card:

• 🚀 Vincular à fila — abre o assistente que cria/víncula a fila e ativa a integração;
• ✏️ Editar — abre o mesmo formulário para alterar nome, URL, eventos e token;
• 📄 Duplicar — cria uma cópia da integração com o nome (cópia);
• 🗑️ Excluir — remove a integração (confirme na janela).

🔔 Eventos disponíveis

Na aba Integrações por Canal (9 opções)

Na aba Integrações por Fila (6 opções)

🎯 Entendendo “Tickets em aberto” e “Tickets pendentes”

Essa configuração é muito importante e costuma gerar dúvidas.

Ela define de quais tickets você quer receber o webhook de mensagem.

📌 Regra simples:

• Se “Ticket em atendimento” (aberto) estiver ativado → você receberá webhook das mensagens de tickets com status Aberto.
• Se “Ticket pendente” estiver ativado → você receberá webhook das mensagens de tickets com status Pendente.
• Se os dois estiverem desativados ❌ → você não receberá nenhum webhook de mensagem.

🧠 Exemplo prático

Existe 1 ticket Aberto e 1 ticket Pendente:

🧪 Testando o webhook

Dentro do formulário (canal ou fila), clique em Testar integração:

1. O NextChat envia uma requisição de teste real para a URL (feita pelo servidor, com o mesmo cabeçalho de autenticação usado nos envios reais);
2. O corpo enviado no teste é:

   {
     "event": "test",
     "origin": "webhook-config",
     "timestamp": "2026-08-15T12:00:00.000Z"
   }

3. O resultado mostra Status HTTP e Duração:
   • ✅ Sucesso → a URL respondeu com status 2xx;
   • ❌ Falha → a URL não respondeu ou respondeu com erro (status 4xx/5xx, tempo excedido, URL inacessível etc.).

🔑 Como o token é enviado (autenticação)

O campo Bearer Token / API Key é opcional. Quando preenchido, o NextChat envia o token no cabeçalho da requisição:

X-N8N-API-KEY: seu-token-aqui

🔁 Retentativas e comportamento de envio

• O envio é feito via requisição POST, com Content-Type: application/json;
• O primeiro envio acontece com um pequeno atraso de 3 segundos após o evento;
• Se a URL falhar, o NextChat tenta mais 2 vezes (total de 3 tentativas), com intervalo fixo de 3 minutos entre elas;
• Após as tentativas, se ainda falhar, o envio fica registrado como falha (você pode acompanhar na fila SendWebhook do Bull Board e nos logs do servidor).

🛠️ Problemas comuns e como verificar

1. Nada chega no destino

Verifique, nesta ordem:

1. Integração Ativada (canal) está ligada? Ou a integração (fila) está vinculada a uma fila e o ticket está nessa fila?
2. A URL está correta e acessível (use o botão Testar integração)?
3. Os eventos estão marcados? Lembre-se: sem eventos marcados, nada é enviado.
4. “Ticket em atendimento” / “Ticket pendente” estão ativados? Se ambos estiverem desligados, nenhuma mensagem gera webhook.
5. É uma mensagem de grupo? Então “Mensagens de grupo” precisa estar ativada.
6. O envio pode estar em retentativa (atraso de 3s + até 2 novas tentativas com 3 min de intervalo).

2. Teste falha

• Confira se a URL usa https:// e está acessível de fora (firewall/SSL);
• Se o destino exige autenticação, confira o token;
• Se o destino responde com erro (ex.: 401/403/404/500), o teste mostra o status HTTP — corrija no destino;
• O tempo limite do teste é de 10 segundos: URLs muito lentas podem falhar no teste, mas funcionar em produção.

3. Como confirmar que está funcionando de verdade

• Testar integração → confirma que a URL aceita requisições;
• Gere um evento real (envie/receba uma mensagem no canal/fila) e veja se o destino recebeu;
• N8N: abra o fluxo → aba Executions e veja se o nó Webhook recebeu a requisição;
• Servidor: na fila SendWebhook do Bull Board você vê os envios, tentativas e falhas. Em caso de erro, os logs do backend registram WebHook -> Webhook: error.

🔄 Diferença entre WebHook e API

Resumo:

• 🔔 WebHook → O NextChat envia informações para você.
• 🧭 API → Você envia informações para o NextChat.

📚 Modelos para Estudo

• Baixe e importe o exemplo de fluxo compatível com o NextChat
• Baixe e importe o modelo com exemplos de endpoints adicionais

🧠 Node NextChat para N8N

Recomenda-se sempre consultar a documentação oficial da API, pois o pacote pode não conter todos os endpoints disponíveis.

📦 https://www.npmjs.com/package/n8n-nodes-nextchat-api