Pular para o conteúdo principal
Versão: 0.4 · atual

Configurar notificações do Slack

Guia de instruçõesRevisado em 11 de outubro de 2026
Aplica-se a:Excubius 0.4Funções: Administrador de entidade
PlanosFree · Core · Pro · EnterpriseImplantaçãoAuto-hospedado

O Excubius anuncia os alertas no Slack: quando um alerta é aberto, quando a severidade dele aumenta e quando ele é resolvido. Você escolhe os canais por entidade, e cada entidade abaixo os herda até definir os próprios. Este guia mostra como conectar um aplicativo do Slack uma única vez, adicionar canais para uma entidade e testá-los, e como uma mensagem é roteada.

Antes de começar​

  • Para adicionar canais, você precisa da função Entity admin (administrador de entidade) na entidade.
  • Para criar o aplicativo do Slack, você precisa de permissão para instalar aplicativos no seu workspace do Slack.
  • Para entregar o token do aplicativo ao Excubius, você precisa de acesso ao servidor: sudo nele ou o pacote do instalador.

Conectar um aplicativo do Slack​

Você faz isso uma vez por instalação.

  1. Acesse https://api.slack.com/apps, selecione Create New App, escolha From scratch, dê a ele um nome que a sua equipe reconheça e escolha o seu workspace.

  2. Em OAuth & Permissions, adicione o escopo de token de bot chat:write. O Excubius não precisa de mais nada.

  3. Selecione Install to Workspace e permita a instalação. Copie o Bot User OAuth Token, que começa com xoxb-.

  4. No servidor, assuma a conta de serviço com sudo -iu excubius e defina o token em /opt/excubius/.env:

    SLACK_BOT_TOKEN=xoxb-…
    SLACK_DEFAULT_CHANNEL=#alerts

    SLACK_DEFAULT_CHANNEL recebe os avisos e os alertas críticos de todas as entidades que não têm um canal próprio em nenhum nível acima delas. Ele é #alerts quando você o omite.

  5. Reinicie a plataforma:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

O instalador também pede o token de bot do Slack e o canal padrão; sudo ./install.sh --reconfigure pede novamente. Enquanto nenhum token estiver definido, Settings › Notifications exibe Slack is not configured on the server e nada é enviado.

Adicionar um canal para uma entidade​

  1. No Slack, abra o canal, por exemplo #ciguapa-alerts, e convide o aplicativo para ele, por exemplo com /invite @Monitoring. O aplicativo só pode publicar nos canais dos quais faz parte.
  2. No Excubius, abra Settings › Notifications e escolha a entidade no seletor, por exemplo Veredas Ltda..
  3. Selecione Add Slack channel.
  4. Preencha os campos:
    • Name: para a sua equipe, por exemplo Alertas Veredas.
    • Slack channel: #name em letras minúsculas ou o ID do canal, como C0123456789.
    • Minimum: a menor severidade publicada, Info, Warning ou Critical. Os alertas abaixo dela não são publicados.
    • Message language: English ou Español. O espanhol exige a opção de recurso ui.i18n; sem ela, o campo informa que as mensagens estão em inglês.
  5. Selecione Add Slack channel.
  6. Selecione Test no novo canal.

Uma mensagem de teste aparece no canal do Slack e o Excubius exibe Test message sent. Se o Slack a recusar, o erro indica o motivo, por exemplo not_in_channel: convide o aplicativo para o canal, verifique o nome do canal e teste novamente.

Os alertas da Veredas Ltda. e de tudo o que está abaixo dela passam a ir para esse canal. Uma entidade pode ter vários canais, por exemplo um para avisos e outro apenas para alertas críticos.

Desativar, alterar ou remover um canal​

Na linha do canal:

  • Use a chave dele para desativá-lo sem removê-lo e ativá-lo novamente mais tarde. Enquanto todos os canais de uma entidade estiverem desativados, a entidade usa os canais herdados de cima.
  • Selecione Edit para alterar qualquer campo e, em seguida, Save.
  • Selecione Remove para parar de enviar para ele. O canal em si continua no Slack.

Como uma mensagem encontra o canal​

A página mostra o resultado para a entidade escolhida em Where alerts go: os canais próprios dela, os canais herdados com a entidade de onde vêm ou o canal padrão do servidor.

SituaçãoPara onde o alerta vai
A entidade do alerta tem canais habilitadosPara os canais próprios dela, cada um filtrado pelo respectivo Minimum
Ela não tem nenhum, mas um ancestral temPara os canais do ancestral mais próximo que tenha algum
Nenhuma entidade no caminho tem canalPara SLACK_DEFAULT_CHANNEL, no caso de avisos e alertas críticos
Nenhum canal e nenhum canal padrãoPara lugar nenhum; a página informa isso

Cada mensagem contém o recurso e o caminho da entidade dele, a verificação, o valor em relação ao limite e onde esse limite está definido, há quanto tempo a condição persiste, a ação sugerida do catálogo de verificações quando houver uma e um link para o alerta. As mensagens nunca citam o nome do produto.

O que mantém o canal tranquilo:

  • Um alerta por condição. As repetições atualizam o alerta e não enviam nada.
  • Período de silêncio. No máximo uma mensagem por condição a cada 10 minutos, a menos que a severidade aumente. A configuração de servidor EXCUBIUS_NOTIFY_QUIET_MINUTES altera o período.
  • Causa raiz. Quando um recurso não pode ser alcançado, um único alerta crítico Cannot reach é enviado, e os outros alertas do recurso aguardam até que ele seja resolvido.
  • Silenciamentos e janelas de manutenção. Nada é enviado enquanto eles duram; o que o canal ainda não recebeu é enviado quando eles terminam, se ainda se aplicar.
  • Sem redução de severidade. Uma queda de crítico para aviso é registrada na linha do tempo do alerta, não enviada. Uma resolução só é enviada quando a abertura também foi.
  • Opções de recurso desativadas. Os alertas de módulos cuja opção de recurso está desativada nunca são enviados, assim como as recomendações de segurança.

O Slack nunca atrapalha o monitoramento: os resultados são armazenados e avaliados primeiro, e as mensagens são enviadas logo depois e por uma varredura em segundo plano a cada 15 segundos. Uma entrega com falha é registrada na linha do tempo do alerta e repetida nas próximas varreduras, em um total de três tentativas.

Fazer isso com a API​

TarefaSolicitação
Ver os canais de uma entidade e o roteamento efetivo delaGET /api/v1/entities/{id}/channels
Adicionar um canalPOST /api/v1/entities/{id}/channels
Alterar, desativar ou ativarPATCH /api/v1/channels/{id} com qualquer um de name, config, min_severity, locale, enabled
RemoverDELETE /api/v1/channels/{id}
Enviar uma mensagem de testePOST /api/v1/channels/{id}/test. Responde {"ok": true} ou {"ok": false, "error": "not_in_channel"} com o motivo do Slack
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/channels" -d '{
"kind": "slack", "name": "Ciguapa alerts", "config": {"channel": "#ciguapa-alerts"},
"min_severity": "warning", "locale": "es"
}'