Configure Slack notifications
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:
sudoon it, or the installer package.
Connect a Slack app
You do this once per installation.
-
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. -
Under OAuth & Permissions, add the bot token scope
chat:write. Excubius needs nothing else. -
Select Install to Workspace and allow it. Copy the Bot User OAuth Token, which starts with
xoxb-. -
On the server, become the service account with
sudo -iu excubiusand set the token in/opt/excubius/.env:SLACK_BOT_TOKEN=xoxb-…SLACK_DEFAULT_CHANNEL=#alertsSLACK_DEFAULT_CHANNELreceives the warnings and criticals of every entity that has no channel of its own anywhere above it. It is#alertswhen you leave it out. -
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
- 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. - In Excubius, open Settings › Notifications and choose the entity in the picker, for example Ciguapa Inc..
- Select Add Slack channel.
- Fill in the fields:
- Name: for your team, for example Ciguapa alerts.
- Slack channel:
#namein lower case, or the channel ID, such asC0123456789. - 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.
- Select Add Slack channel.
- 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.
| Situation | Where the alert goes |
|---|---|
| The alert's entity has enabled channels | Its own channels, each filtered by its Minimum |
| It has none, but an ancestor has | The channels of the nearest ancestor that has any |
| No entity on the path has a channel | SLACK_DEFAULT_CHANNEL, for warnings and criticals |
| No channel and no default channel | Nowhere; 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_MINUTESchanges 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
| Task | Request |
|---|---|
| See an entity's channels and its effective routing | GET /api/v1/entities/{id}/channels |
| Add a channel | POST /api/v1/entities/{id}/channels |
| Change, turn off or on | PATCH /api/v1/channels/{id} with any of name, config, min_severity, locale, enabled |
| Remove | DELETE /api/v1/channels/{id} |
| Send a test message | POST /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"
}'