Skip to main content
Version: 0.4 · current

Configure Slack notifications

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Excubius announces alerts in Slack: when one opens, when its severity rises and when it resolves. You choose the channels per entity, and every entity below inherits them until it sets its own. This guide shows how to connect a Slack app once, add channels for an entity, test them, and how a message is routed.

Before you begin​

  • To add channels, you need the Entity admin role on the entity.
  • To create the Slack app, you need permission to install apps in your Slack workspace.
  • To give the app's token to Excubius, you need access to the server: sudo on it, or the installer package.

Connect a Slack app​

You do this once per installation.

  1. Go to https://api.slack.com/apps, select Create New App, choose From scratch, give it a name your team recognises and pick your workspace.

  2. Under OAuth & Permissions, add the bot token scope chat:write. Excubius needs nothing else.

  3. Select Install to Workspace and allow it. Copy the Bot User OAuth Token, which starts with xoxb-.

  4. On the server, become the service account with sudo -iu excubius and set the token in /opt/excubius/.env:

    SLACK_BOT_TOKEN=xoxb-…
    SLACK_DEFAULT_CHANNEL=#alerts

    SLACK_DEFAULT_CHANNEL receives the warnings and criticals of every entity that has no channel of its own anywhere above it. It is #alerts when you leave it out.

  5. Restart the platform:

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

The installer asks for the Slack bot token and the default channel too; sudo ./install.sh --reconfigure asks again. Until a token is set, Settings › Notifications says Slack is not configured on the server and nothing is sent.

Add a channel for an entity​

  1. In Slack, open the channel, for example #ciguapa-alerts, and invite the app to it, for example with /invite @Monitoring. The app can post only in channels it belongs to.
  2. In Excubius, open Settings › Notifications and choose the entity in the picker, for example Ciguapa Inc..
  3. Select Add Slack channel.
  4. Fill in the fields:
    • Name: for your team, for example Ciguapa alerts.
    • Slack channel: #name in lower case, or the channel ID, such as C0123456789.
    • Minimum: the lowest severity posted, Info, Warning or Critical. Alerts below it are not posted.
    • Message language: English or Español. Spanish needs the feature ui.i18n; without it the field says that messages are in English.
  5. Select Add Slack channel.
  6. Select Test on the new channel.

A test message appears in the Slack channel and Excubius shows Test message sent. If Slack refuses it, the error names the reason, for example not_in_channel: invite the app to the channel, check the channel's name, and test again.

Alerts from Ciguapa Inc. and everything below it now go to that channel. An entity can have several channels, for example one for warnings and one for criticals only.

Turn off, change or remove a channel​

On the channel's row:

  • Use its switch to turn it off without removing it, and on again later. While every channel of an entity is off, the entity uses the channels inherited from above.
  • Select Edit to change any field, then Save.
  • Select Remove to stop sending to it. The channel itself stays in Slack.

How a message finds its channel​

The page shows the result for the chosen entity under Where alerts go: its own channels, or the inherited ones with the entity they come from, or the server's default channel.

SituationWhere the alert goes
The alert's entity has enabled channelsIts own channels, each filtered by its Minimum
It has none, but an ancestor hasThe channels of the nearest ancestor that has any
No entity on the path has a channelSLACK_DEFAULT_CHANNEL, for warnings and criticals
No channel and no default channelNowhere; the page says so

Each message carries the resource and its entity path, the check, the value against the threshold and where that threshold is set, how long the condition has held, the suggested action from the check catalog when there is one, and a link to the alert. Messages never name the product.

What keeps the channel quiet:

  • One alert per condition. Repeats update the alert and send nothing.
  • Quiet period. At most one message per condition every 10 minutes, unless the severity rises. The server setting EXCUBIUS_NOTIFY_QUIET_MINUTES changes the period.
  • Root cause. When a resource cannot be reached, one critical Cannot reach alert is sent and the resource's other alerts wait until it resolves.
  • Silences and maintenance windows. Nothing is sent while they last; what the channel has not heard yet goes out when they end, if it still applies.
  • No de-escalations. A drop from critical to warning is recorded in the alert's timeline, not sent. A resolution is sent only when the opening was.
  • Switched-off features. Alerts of modules whose feature is off are never sent, and neither are security recommendations.

Slack is never in the way of monitoring: results are stored and evaluated first, and messages go out right after and from a background sweep every 15 seconds. A failed delivery is recorded in the alert's timeline and retried by the next sweeps, three attempts in all.

Do it with the API​

TaskRequest
See an entity's channels and its effective routingGET /api/v1/entities/{id}/channels
Add a channelPOST /api/v1/entities/{id}/channels
Change, turn off or onPATCH /api/v1/channels/{id} with any of name, config, min_severity, locale, enabled
RemoveDELETE /api/v1/channels/{id}
Send a test messagePOST /api/v1/channels/{id}/test. Answers {"ok": true}, or {"ok": false, "error": "not_in_channel"} with Slack's reason
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/channels" -d '{
"kind": "slack", "name": "Ciguapa alerts", "config": {"channel": "#ciguapa-alerts"},
"min_severity": "warning", "locale": "es"
}'