Configurações
Webhooks
Avisar um sistema externo, na hora, cada vez que algo acontece no Hub.
Nesta página
A tela Webhooks faz o Hub avisar um sistema externo — n8n, um agente de IA, a automação do cliente — toda vez que algo acontece aqui: um chamado aberto, um SLA estourado, um servidor em alerta, um deploy que falhou. Em vez de o outro lado ficar perguntando "mudou alguma coisa?" de tempos em tempos, o Hub manda o aviso no momento em que o fato acontece.
É o par do MCP, não o substituto. O webhook entrega o que aconteceu, em poucas linhas; quem quiser o conteúdo completo — ou quiser agir — continua usando o MCP. Por isso cada aviso traz o link da tela e a sugestão de consulta correspondente.
Onde fica
Em Configurações, abra Webhooks. Exige a permissão Gerenciar os webhooks de saída; administradores já a têm.
Cadastrar um destino
- Clique em + Adicionar webhook.
- Em Nome, descreva o destino (ex.: n8n produção). É esse nome que aparece na lista e no aviso de pausa.
- Empresa (opcional) deixa o destino amarrado a uma empresa. Em branco, ele vale para todas.
- Em URL de destino, cole o endereço que vai receber. Só https, e precisa ser um endereço acessível pela internet.
- Se o destino exigir uma credencial, preencha Cabeçalhos do destino (veja abaixo). Se não exigir, pule.
- Marque os Eventos assinados e clique em Salvar.
O segredo aparece uma única vez, no bloco Guarde o segredo agora. É com ele que o seu sistema confere a assinatura de cada entrega. Se perder, marque Gerar um segredo novo ao salvar na edição — o anterior deixa de valer na hora.
Cabeçalhos do destino
A assinatura do Hub serve para o seu sistema conferir que a mensagem veio daqui. Ela não faz o caminho inverso: não identifica o Hub para quem recebe. A maioria dos serviços prontos — Cursor, n8n, Zapier, API de cliente — exige uma credencial própria e recusa a chamada sem ela.
É para isso que serve o bloco Cabeçalhos do destino. O campo é opcional: destino que só confere a assinatura não precisa de nada aqui.
- Clique em + Adicionar cabeçalho.
- No primeiro campo, o nome do cabeçalho que o destino pediu (ex.:
AuthorizationouX-API-Key). - No segundo, o valor (ex.:
Bearer sua-chave-aqui). Copie exatamente como o serviço entregou.
Na edição, o nome volta preenchido e o valor aparece como Guardado. Deixe em branco para manter o que está lá; digite algo só quando quiser trocar.
Cabeçalhos que o Hub usa por conta própria — os que começam comX-Vitreum-, além deContent-TypeeHost— não podem ser definidos aqui, e a tela avisa se você tentar. São eles que carregam a assinatura e o formato da mensagem.
Eventos assinados
Os eventos vêm agrupados por área. Hoje o Hub publica:
- Chamados — aberto, status alterado, prioridade alterada, responsável alterado, reaberto, resolvido, fechado e SLA estourado.
- Infraestrutura — alerta aberto e alerta recuperado.
- Cards (Kanban) — card movido de etapa.
- Projetos — status do projeto alterado.
- Deploy — deploy concluído e deploy falhou.
- WhatsApp — mensagem recebida, mensagem enviada ao cliente, conversa iniciada e conversa encerrada.
O botão Marcar todos de uma área assina a área inteira, e não a lista de eventos que existe hoje: quando um evento novo nascer naquela área, esse destino passa a recebê-lo automaticamente. Para assinar só o que existe agora, marque os eventos um a um.
Não existe "assinar tudo". Cada destino recebe só o que foi marcado nele, e área nova não começa a enviar sozinha para destinos antigos — um sistema montado para receber chamado não vai passar a receber ponto eletrônico sem alguém decidir isso.
Dois casos que costumam gerar dúvida: o pedido de aprovação ao cliente é o evento card movido com destino Aguardando aprovação — não existe evento separado; e deploy manda um aviso por deploy, não um por servidor, com a contagem de sucessos e falhas dentro.
Os eventos de WhatsApp são a forma de levar a conversa do inbox para outro sistema — sem precisar apontar o painel da Z-API para dois lugares. O que chega é o aviso do Hub, já com o contexto que ele resolveu: a conversa, o contato, a empresa e o chamado.
- Mensagem enviada ao cliente cobre as três origens — a resposta do agente pela tela, a do operador de IA e a confirmação automática que o Hub manda ao abrir o chamado. O aviso interno a um colega não entra: ele não é atendimento e não aparece no inbox.
- Conversa iniciada sai depois do chamado automático e da distribuição, por isso é a única que traz o número do chamado e o agente responsável.
- Quando a mensagem tem anexo, o aviso diz o tipo e o nome do arquivo — o arquivo em si não acompanha. Para abri-lo, use o inbox ou o MCP.
O aviso nunca carrega as credenciais do número de WhatsApp: a instância aparece só pelo nome que você deu a ela em Configurações.
Se você tem mais de um número, o campo Números de WhatsApp, logo abaixo da lista de eventos, escolhe quais deles este destino recebe. Em branco, ele recebe os de todos. O recorte vale só para os eventos de WhatsApp — os de chamado, projeto ou deploy que o mesmo destino assine continuam chegando normalmente.
O campo só aparece se houver número cadastrado em Configurações → Integrações → WhatsApp. Na lista de destinos, o recorte aparece embaixo do nome ("WhatsApp: Comercial") — assim dá para ver por que um destino recebe menos que outro sem precisar abrir a edição.
Como conferir a assinatura
Cada entrega chega com os cabeçalhos X-Vitreum-Signature, X-Vitreum-Timestamp, X-Vitreum-Event e X-Vitreum-Delivery. A assinatura é um HMAC-SHA256 do timestamp e do corpo, separados por um ponto, usando o segredo do destino.
No seu sistema: recalcule o HMAC sobre timestamp + "." + corpo e compare com o cabeçalho. Recuse o que vier com timestamp muito antigo — é assim que se descarta uma entrega capturada e reenviada por outra pessoa.
O corpo é sempre o mesmo envelope: id, evento, ocorrido_em, tenant, dados e links.
Guarde oid. Ele é o mesmo em um reenvio e nas novas tentativas, e é por ele que o seu sistema reconhece uma repetição em vez de processar o mesmo fato duas vezes. A ordem de chegada não é garantida — use oocorrido_empara ordenar.
Chat interno: as conversas de um robô
Os eventos de Chat interno chegam a um destino por dois caminhos. O primeiro são os grupos integrados — aqueles em que o dono ligou a chave Enviar aos webhooks. O segundo é o campo Chat interno — conversas de, no bloco de eventos do destino: escolha ali o usuário do robô e o destino passa a receber as mensagens que outras pessoas enviam nas conversas dele, inclusive as diretas.
- O destino recebe só as conversas de que aquele agente participa, e não recebe de volta o que o próprio agente escreve.
- Com o campo preenchido, o destino deixa de receber grupos integrados de que o agente não participa.
- O campo só aparece para quem tem, além da permissão de webhooks, a permissão Ligar grupos do Chat interno aos webhooks de saída.
Quem conversa com um agente ligado a um destino vê o selo Integrado na conversa. Use este campo para usuários de robô — apontar para cá o chat de uma pessoa envia as conversas dela para fora do Hub.
Log de disparos, tentativas e reenvio
Abaixo da lista de destinos fica o Log de disparos: tudo o que o Hub enviou, para todos os destinos, nos últimos 30 dias — do mais recente para o mais antigo, com a quantidade total ao lado do título. Cada linha mostra o horário, o evento, o destino, a situação (Entregue, Falhou ou pendente), o código HTTP, a tentativa, o tempo de resposta e o trecho devolvido pelo destino.
- Ver conteúdo abre o que foi enviado naquele disparo: o JSON completo, o identificador do evento e a resposta do destino. É por aqui que você confere exatamente o que o seu sistema recebeu.
- Reenviar manda o mesmo conteúdo de novo, com o mesmo identificador de evento — o seu sistema reconhece como repetição.
- Os botões Entregues, Falharam e Pendentes filtram por situação (clique de novo para soltar); o campo ao lado filtra pelo tipo de evento.
- Na linha de um destino, o ícone de prancheta mostra só os disparos daquele destino. Limpar filtros volta ao log inteiro.
- O ícone de Enviar entrega de teste, na linha do destino, dispara uma carga de teste na hora — útil para confirmar que o endereço responde antes de depender dele.
O log mostra o que saiu. Um acontecimento que nenhum destino assina não gera disparo e não aparece aqui — se algo "não chegou", confira primeiro os eventos marcados no destino.
Quando uma entrega falha, o Hub tenta de novo 5 vezes, esperando 1, 2, 5, 15 e 60 minutos entre as tentativas. Enquanto houver tentativa pela frente, a linha mostra o horário da próxima.
Depois de 20 entregas seguidas perdidas, o destino é pausado automaticamente e você recebe um aviso no sino. Ele aparece com a tarja Pausado e o motivo da última falha. Para religar, use o botão de ativar na linha — isso também zera a contagem.
Acompanhar a saúde
A faixa no topo conta o parque inteiro: Ativos, Pausados, Com falha e Falhas 24h. Clicar numa delas filtra a lista por aquele recorte; clicar de novo solta o filtro. O botão de liga/desliga da linha ativa e desativa o destino na hora.
Remover um destino o faz parar de receber imediatamente. O histórico de entregas é mantido.
O que o Hub recusa
A URL é conferida no cadastro e de novo a cada entrega. São recusados endereços sem https, endereços com usuário e senha embutidos e, principalmente, qualquer destino que aponte para dentro de uma rede privada — incluindo os endereços internos da sua própria infraestrutura.
Essa última regra não é burocracia: sem ela, um endereço interno digitado por engano faria o Hub buscar dados de dentro da rede e entregá-los a quem configurou o webhook. Se você precisa levar eventos para um sistema que só existe na rede interna, exponha um endereço público para ele ou use um intermediário.