Webhooks e N8N

Um Webhook permite que o Galaxy Chat notifique outro sistema (como N8N, Zapier, Make, CRM ou backend próprio) automaticamente e em tempo real sempre que um evento ocorrer: uma nova mensagem chegar, um ticket for criado ou transferido, um agendamento for remarcado ou um card avançar no funil de vendas.

👉 Você não precisa fazer consultas periódicas (polling) ao sistema.
👉 O Galaxy Chat faz uma requisição HTTP POST com os dados em formato JSON para a sua URL configurada no exato instante do evento.

📍 Onde Configurar

No menu lateral, acesse: 👉 Automação e Integrações › Webhooks/N8N

(Disponível para perfis Administrador e Supervisor).

A tela centraliza a gestão em 5 abas especializadas:

graph TD
    A[Webhooks / N8N] --> B[1. Integrações por Canal]
    A --> C[2. Integrações por Fila N8N]
    A --> D[3. Webhook da Agenda]
    A --> E[4. Webhook do Kanban]
    A --> F[5. Webhook do Kanban Pro]

Integrações por Canal: Aplica-se a todos os atendimentos de um canal (ex.: um número de WhatsApp conectado);
Integrações por Fila (N8N): Dispara eventos apenas para os tickets daquela fila específica;
Webhook da Agenda: Notifica sobre criação, alteração, cancelamento ou remarcação de horários de atendimento;
Webhook do Kanban: Envia atualizações dos contatos/cards do Kanban CRM (movimentação de etapa e vitória);
Webhook do Kanban Pro: Dispara eventos dos quadros avançados (criação, edição, movimentação e arquivamento de cards).

🚀 Como Configurar Passo a Passo

1. Pelo Canal (Escopo Global do Número)

Acesse a aba Integrações por Canal;
Clique em Configurar no canal de WhatsApp ou rede social desejada;
Ative o interruptor Integração Ativada;
Digite a sua URL do Webhook (ex.: https://seu-n8n.com/webhook/galaxy-chat);
Marque quais Eventos devem disparar o webhook;
(Opcional) Em Mostrar configurações avançadas, informe o Bearer Token / API Key;
Clique em Testar integração e depois em Salvar.

2. Pela Fila (Integrações com N8N)

Acesse a aba Integrações por Fila;
Clique em Nova Integração N8N;
Dê um nome identificador, insira a URL e selecione os eventos;
Clique em Salvar;
Clique no botão de Foguete (Vincular à fila) para que o assistente crie ou associe uma fila àquela integração;
A opção "Inicia Integração ao transferir" fica ativa por padrão: assim que um ticket cai nessa fila, o webhook é acionado imediatamente usando a última mensagem recebida.

🔔 Eventos Disponíveis por Aba

Aba 1: Integrações por Canal (9 Eventos)

Evento	O que Dispara
Mensagem recebida	Qualquer nova mensagem recebida de um cliente no canal.
Mensagem enviada	Mensagens enviadas por atendentes humanos, bots ou API.
Novo ticket	Disparado tanto quando o ticket é aberto manualmente por um operador quanto na chegada de uma nova conversa.
Ticket transferido	Quando o atendimento é redirecionado para outra fila ou usuário.
Ticket fechado	Quando o ticket é encerrado e concluído.
Ticket em atendimento	Filtro essencial: permite envio de mensagens de tickets com status Aberto.
Ticket pendente	Filtro essencial: permite envio de mensagens de tickets com status Pendente (aguardando aceite).
Mensagens de grupo	Habilita o disparo de webhooks para mensagens originadas em grupos de WhatsApp.
Enviar mídia em base64	Inclui o arquivo (áudio, foto, documento) codificado em base64 no campo `mediaBase64`.

Aba 2: Integrações por Fila (6 Eventos)

A aba de fila foca exclusivamente no fluxo de conversas daquele setor:

Mensagem recebida (na fila vinculada)
Mensagem enviada (na fila vinculada)
Ticket em atendimento (abertos)
Ticket pendente (na espera)
Mensagens de grupo
Enviar mídia em base64

⚠️Regra Crítica: Tickets Abertos vs. Tickets Pendentes

Se os interruptores "Ticket em atendimento" e "Ticket pendente" estiverem ambos desligados, nenhum webhook de mensagem será enviado, mesmo que "Mensagem recebida" esteja ativada! Certifique-se de marcar pelo menos um dos dois para receber mensagens.

📅 Webhook da Agenda, Kanban e Kanban Pro

Nas abas 3, 4 e 5 você integra os módulos analíticos:

Webhook da Agenda

Eventos: Agendamento criado, alterado, remarcado, cancelado, excluído ou com mudança de status (ex.: Confirmado ou Concluído);
Filtro: Escolha calendários específicos ou deixe em branco para receber de todos os locais.

Webhook do Kanban CRM

Eventos: Card criado, alterado, movido de etapa, excluído, mudança de responsável (troca de carteira) ou Mudança de status (etapa ganha) quando atinge a lane de venda concluída.

Webhook do Kanban Pro

Eventos: Card criado, alterado, movido de etapa, excluído, mudança de responsável do card e Mudança de status (ganho ou arquivado);
Filtro por Quadros: Monitore apenas os quadros desejados ou toda a operação.

🔑 Autenticação e Cabeçalhos HTTP

Ao configurar o Bearer Token / API Key:

Nas abas de Canal e Fila, o sistema envia a chave no cabeçalho padronizado do N8N:
X-N8N-API-KEY: seu_token_aqui
Nas abas de Agenda e Kanban, a chave é transmitida no cabeçalho tradicional:
Authorization: Bearer seu_token_aqui

🧪 Testando o Webhook

Ao clicar no botão Testar integração, o servidor do Galaxy Chat dispara uma requisição de teste real:

{
  "event": "test",
  "origin": "webhook-config",
  "timestamp": "2026-10-22T10:00:00.000Z"
}

✅ Sucesso: O seu servidor respondeu com status HTTP 200 ou 204.
❌ Falha: A URL não respondeu em até 10 segundos ou retornou erro 4xx ou 5xx.

🔁 Política de Retentativas Automáticas

O envio inicial ocorre com um intervalo de segurança de aproximadamente 3 segundos após o evento;
Se o seu endpoint estiver offline ou retornar erro, o Galaxy Chat realiza mais 2 tentativas automáticas (totalizando 3 tentativas), com intervalo de 3 minutos entre cada disparo;
O histórico completo de envios pode ser conferido pelo ícone de relógio (Últimos envios).

📦 Estruturas de Payload JSON

1. Novo Ticket Aberto Automaticamente (`NewTicket`)

{
  "Type": "NewTicket",
  "messageBody": "Olá, gostaria de saber os valores dos planos",
  "ticket": {
    "id": 1450,
    "status": "pending",
    "protocol": "202610221450",
    "queueId": 2,
    "userId": null,
    "apiConfig": "CRM_CLIENTE_9876"
  },
  "contact": {
    "id": 850,
    "name": "Mariana Souza",
    "phoneNumber": "5511999998888",
    "email": "mariana@email.com",
    "isGroup": false
  },
  "whatsapp": {
    "id": 1,
    "name": "WhatsApp Comercial"
  }
}

2. Mensagem Recebida ou Enviada

{
  "messageId": "3EB09F7C2A1E",
  "messageBody": "Sim, confirmo o recebimento!",
  "timestamp": 1792620000,
  "status": "received",
  "fromMe": false,
  "mediaType": "chat",
  "mediaUrl": null,
  "mediaBase64": null,
  "isDeleted": false,
  "ticket": {
    "id": 1450,
    "status": "open",
    "protocol": "202610221450",
    "queueId": 2,
    "apiConfig": null,
    "isGroup": false
  },
  "contact": {
    "id": 850,
    "name": "Mariana Souza",
    "phoneNumber": "5511999998888"
  },
  "whatsapp": {
    "id": 1,
    "name": "WhatsApp Comercial"
  }
}

✨Identificação de Mensagens em Grupos

Em mensagens de grupos do WhatsApp (ticket.isGroup = true), o objeto contact representa o grupo como um todo, enquanto o objeto contactmessage traz os dados específicos do participante que digitou a mensagem.

📍 Onde Configurar​

🚀 Como Configurar Passo a Passo​

1. Pelo Canal (Escopo Global do Número)​

2. Pela Fila (Integrações com N8N)​

🔔 Eventos Disponíveis por Aba​

Aba 1: Integrações por Canal (9 Eventos)​

Aba 2: Integrações por Fila (6 Eventos)​

📅 Webhook da Agenda, Kanban e Kanban Pro​

Webhook da Agenda​

Webhook do Kanban CRM​

Webhook do Kanban Pro​

🔑 Autenticação e Cabeçalhos HTTP​

🧪 Testando o Webhook​

🔁 Política de Retentativas Automáticas​

📦 Estruturas de Payload JSON​

1. Novo Ticket Aberto Automaticamente (NewTicket)​

2. Mensagem Recebida ou Enviada​