Slack Notifications

Slack can be used as a notification destination in Causely.

All Slack delivery runs through the Causely Mediator.

How you define Slack destinations depends on your setup:

Managed Notifications (recommended)
Routing rules and Slack credentials are configured in the Causely UI. The UI stores configuration that the Mediator reads at runtime.
Mediator-based configuration (advanced)
Define Slack destinations programmatically with environment variables or Kubernetes secrets instead of the UI. Uses the same Mediator delivery path as managed notifications.

For routing rules and filters in the UI, see Set up notification routing in the UI.

Delivery modes

Causely can deliver problem and defect notifications to Slack in two ways. Configure one mode per notification destination; you do not need both a webhook and a bot token for the same destination.

Mode	URL field	Token field	Delivery
Incoming webhook	`https://hooks.slack.com/services/...`	Leave empty	One combined message per alert
Bot API (threaded)	Channel ID (for example, `C01234567` or `G01234567` for private channels)	Bot token (`xoxb-...`)	Parent message + threaded replies

The bot must be a member of the channel (invite it with /invite @YourBotName). Use the channel ID (for example, C01234567) and not the channel name (for example, #alerts) in the URL field, as channel names are not supported in the configuration.

The mediator selects the mode automatically from the URL and token values.

Option A: Incoming webhook (simple)

Best when you want a single message per alert and already have (or can create) an incoming webhook.

1. Create a Slack incoming webhook

Open Slack API apps or use Slack → Tools → Workflow Builder / Apps depending on your workspace policy.
Create or select an app, then enable Incoming Webhooks.
Add New Webhook to Workspace and pick the target channel.
Copy the webhook URL (https://hooks.slack.com/services/T.../B.../...).

2. Configure Causely

Go to Settings → Notifications.
If you haven't already selected a processing mode, choose one now. Click Create.
Complete the notification configuration:

Field	Value
Name	A descriptive name for the notification
Type	Slack
URL	The incoming webhook URL
Token	Leave blank

Alternatively, configure the Mediator with environment variables or a Kubernetes secret instead of using the UI.

Environment variables

Set these on the Causely Mediator deployment. Replace <NAME> with your notification config name.

NOTIFICATION_<NAME>_TYPE=Slack
NOTIFICATION_<NAME>_URL=https://hooks.slack.com/services/T.../B.../...
NOTIFICATION_<NAME>_FILTERS_ENABLED=true

Kubernetes secret

Create a secret labelled causely.ai/notif-config: Slack in the Mediator namespace:

notif_config_type: Slack
notif_config_name: your config name
notif_config_url: webhook URL
notif_config_filters: optional JSON filter rules

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: slack-notification-config
  namespace: causely
  labels:
    causely.ai/notif-config: Slack
stringData:
  notif_config_filters: "[]"
  notif_config_filters_enabled: "true"
  notif_config_global: "false"
  notif_config_name: slack
  notif_config_token: ""
  notif_config_type: Slack
  notif_config_url: https://hooks.slack.com/services/XXX/YYY/ZZZ

3. Verify

Post a test notification from the UI or trigger a real alert. You should see one Block Kit message with header, entity metadata, summary, evidence, remediation, SLOs, labels (when present), and a View button.

Option B: Bot token + channel (threaded)

Best when you want a compact parent message and details in a thread (summary, labels, evidence, remediation as separate replies).

1. Create a Slack app and bot token

Go to https://api.slack.com/apps → Create New App → From scratch.
Open OAuth & Permissions and add the bot token scope:
- chat:write: post messages to channels the bot has joined
Go to Install App and click Install to Workspace (or Reinstall to Workspace if the app is already installed).
Copy the Bot User OAuth Token (xoxb-...) shown on that page.

2. Create or choose a channel

Create or pick a channel (for example, #causely-alerts).
Invite the bot to the channel (required): /invite @YourBotName
Copy the channel ID (required for the Causely URL field):
- Open the channel → channel name → About → scroll down → copy the ID (C... for public, G... for private).

3. Configure Causely

Go to Settings → Notifications.
If you haven't already selected a processing mode, choose one now. Click Create.
Complete the notification configuration:

Field	Value
Name	A descriptive name for the notification
Type	Slack
URL	Channel ID (for example, `C0123456789`)
Token	Bot User OAuth Token (`xoxb-...`)

The token field is optional for webhooks but required when the URL is not a hooks.slack.com webhook.

Alternatively, configure the Mediator with environment variables or a Kubernetes secret instead of using the UI.

Environment variables

Set these on the Causely Mediator deployment. Replace <NAME> with your notification config name.

NOTIFICATION_<NAME>_TYPE=Slack
NOTIFICATION_<NAME>_URL=C0123456789
NOTIFICATION_<NAME>_TOKEN=xoxb-your-bot-token
NOTIFICATION_<NAME>_FILTERS_ENABLED=true

A Bearer prefix on the token is accepted (for example, Bearer xoxb-...).

Kubernetes secret

Create a secret labelled causely.ai/notif-config: Slack in the Mediator namespace. Set notif_config_url to the channel ID and notif_config_token to the bot token.

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: slack-bot-notification-config
  namespace: causely
  labels:
    causely.ai/notif-config: Slack
stringData:
  notif_config_filters: "[]"
  notif_config_filters_enabled: "true"
  notif_config_global: "false"
  notif_config_name: slack-threaded
  notif_config_token: xoxb-your-bot-token
  notif_config_type: Slack
  notif_config_url: C0123456789

4. Verify with curl

curl -s https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer xoxb-your-token" \
  -H "Content-Type: application/json" \
  -d '{"channel":"C0123456789","text":"Causely bot test"}'

Expect "ok": true.

5. Thread layout (bot mode)

For detected problems, Causely posts:

Message	Content
Parent	Header, entity/severity metadata, View button
Thread 1	Summary
Thread 2	Labels
Thread 3	Evidence and impacted SLOs
Thread 4	Remediation

Cleared notifications are sent as a single message. Empty sections are skipped (for example, no labels thread if there are no labels).

Failed thread replies are retried with backoff; remaining sections may be combined into a fallback thread message.

Mediator-based configuration (advanced)

Managed notifications in the UI are the recommended path. If you configure the Mediator directly instead, use the Environment variables or Kubernetes secret sections under Option A or Option B above.

Filters and object type

Notification destinations support filters (severity, namespace, entity type, etc.) and object type (defect vs issue) like other Causely notification targets. Configure these in the same create/edit modal or via notif_config_filters / NOTIFICATION_<NAME>_FILTERS.

Troubleshooting

Symptom	Likely cause	Fix
`not_in_channel`	Bot is not a channel member	`/invite @Bot` in the target channel before sending
`channel_not_found`	Wrong channel ID or bot not in channel	Use channel ID (not `#name`); invite bot to private channels
`invalid_auth`	Bad or revoked token	Reinstall app; copy fresh `xoxb-` token
Webhook works but threading does not	URL still points at webhook	Use channel ID in URL, not `hooks.slack.com`
Threaded mode not used	Missing or invalid token	Token must start with `xox` (after optional `Bearer` prefix)
Notification marked failed but message in Slack	Partial thread delivery	Check mediator logs; retries/fallback may still leave parent visible
UI has no token field	Older UI build	Upgrade UI or set token via env / K8s secret

Managed Notifications
Slack incoming webhooks: https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/
Slack chat.postMessage: https://docs.slack.dev/reference/methods/chat.postMessage

Notification Payload Format

Causely sends structured alert payloads to Slack, including summaries of causal insights and service impact context.
For an example payload and explanation of each field, refer to the Notification Payload Format page.

Delivery modes​

Option A: Incoming webhook (simple)​

1. Create a Slack incoming webhook​

2. Configure Causely​

Environment variables​

Kubernetes secret​

3. Verify​

Option B: Bot token + channel (threaded)​

1. Create a Slack app and bot token​

2. Create or choose a channel​

3. Configure Causely​

Environment variables​

Kubernetes secret​

4. Verify with curl​

5. Thread layout (bot mode)​

Mediator-based configuration (advanced)​

Filters and object type​

Troubleshooting​

Related documentation​

Notification Payload Format​

Delivery modes

Option A: Incoming webhook (simple)

1. Create a Slack incoming webhook

2. Configure Causely

Environment variables

Kubernetes secret

3. Verify

Option B: Bot token + channel (threaded)

1. Create a Slack app and bot token

2. Create or choose a channel

3. Configure Causely

Environment variables

Kubernetes secret

4. Verify with curl

5. Thread layout (bot mode)

Mediator-based configuration (advanced)

Filters and object type

Troubleshooting

Related documentation

Notification Payload Format