Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.svantic.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Slack Integration Guide

This guide walks through setting up a Slack App for Svantic. The basic setup enables outbound notifications (alerts sent to a Slack channel). The optional advanced setup enables bidirectional approval workflows where users can approve or deny directly from Slack.

​
Overview

The integration has two directions:
  1. Outbound (required): Svantic → Slack — alert notifications and approval requests sent to a channel
  2. Inbound (optional): Slack → Svantic — user clicks an interactive button, Slack POSTs the action back to Svantic
For alert notifications only, you need steps 1–5. For interactive approvals, continue with steps 6–7.

​
Step 1: Create a Slack App

  1. Go to api.slack.com/apps and click Create New App
  2. Choose From scratch
  3. Name it (e.g., “Svantic Alerts”) and select your workspace
  4. Click Create App

​
Step 2: Configure Bot Scopes

Under OAuth & Permissions → Scopes → Bot Token Scopes, add:
ScopePurposeRequired?
chat:writeSend messages to channelsYes
chat:updateUpdate messages after approval (replace buttons with “Approved by @user”)Only for interactive approvals

​
Step 3: Install to Workspace

  1. On the OAuth & Permissions page, scroll up and click Install to Workspace
  2. Click Allow on the permission prompt
  3. Copy the Bot User OAuth Token (xoxb-...) — this is your bot token
If you see Request to Install instead of Install to Workspace, your workspace has app approval enabled. Ask a workspace admin to approve the app, or temporarily disable approval in Slack Admin → Manage Apps → Settings.

​
Step 4: Get the Channel ID and Invite the Bot

  1. In Slack, navigate to the channel where you want alerts delivered
  2. Right-click the channel name → View channel details
  3. Scroll to the bottom and copy the Channel ID (e.g., C0123456789)
  4. In the channel, invite the bot:
/invite @Svantic Alerts
Replace “Svantic Alerts” with the name you gave your app in step 1. The bot must be a member of the channel to post messages. To find your bot’s exact name, go to api.slack.com/apps → select your app → App Home → look for the Display Name (Bot).

​
Step 5: Register the Slack Channel in Svantic

​
Via the dashboard

  1. Go to Settings → Channels → click New Channel
  2. Select Slack as the type
  3. Enter a name (e.g., “Engineering Slack”)
  4. Enter the Bot Token (xoxb-...)
  5. Enter the Channel ID (C0123456789)
  6. Click Create
You can also add a Slack channel directly on the Alerts page by clicking Add channel on any alert subscription.

​
Via the API

POST /internal/channels/new
{
  "type": "slack",
  "name": "Engineering alerts",
  "config": {
    "bot_token": "xoxb-your-bot-token",
    "channel_id": "C0123456789"
  }
}
Config FieldWhere to Get It
bot_tokenOAuth & Permissions → Bot User OAuth Token
channel_idRight-click the Slack channel → View channel details → copy the Channel ID

​
Step 5b: Test

Trigger a real event (e.g., register and deregister an agent) with the alert subscription enabled and the Slack channel linked. A notification should appear in the Slack channel.

​
Step 6: Enable Interactivity (Optional)

This step is only needed if you want users to approve or deny requests directly from Slack buttons. Under Interactivity & Shortcuts in your Slack App settings:
  1. Toggle Interactivity to On
  2. Set Request URL to: https://your-gateway-domain/integrations/slack/interactive
  3. Click Save Changes
This tells Slack where to POST when a user clicks an interactive button in a Svantic notification.

​
Step 7: Note Your Signing Secret (Optional)

Only needed for interactive approvals (step 6). Under Basic Information → App Credentials, copy the Signing Secret. Svantic uses this to verify that inbound requests actually come from Slack (and not an attacker spoofing Slack’s payload format).

​
How Approval Buttons Work

​
Outbound (Svantic → Slack)

When a message enters input-required, the SlackRenderer inspects the A2UI spec:
  • Simple approval (1 action field with 2-3 options): renders Slack buttons inline
  • Complex form (multiple fields, sensitive data): renders a summary text with a “Complete in Dashboard” button
The Block Kit message includes metadata linking the buttons to the specific message_id.

​
Inbound (Slack → Svantic)

When a user clicks a button:
  1. Slack POSTs an interaction payload to https://your-gateway/integrations/slack/interactive
  2. Svantic verifies the Slack signing secret:
    • Computes v0:timestamp:body → HMAC-SHA256 with signing secret
    • Compares to the X-Slack-Signature header
    • Rejects if timestamp is stale (>5 minutes)
  3. Svantic extracts the action (approve or deny) and message_id from the payload
  4. Svantic resolves the pending request (same logic as dashboard resolution)
  5. Svantic POSTs back to Slack’s response_url to update the original message:
    • Buttons are replaced with: “Approved by @john at 3:45 PM”
    • This prevents other users from clicking already-resolved buttons

​
Race Conditions

If someone approves from the dashboard at the same moment someone clicks Approve in Slack, the first resolution wins. The second receives a 409 Conflict, and Svantic updates the Slack message to reflect that it was already resolved.

​
Limitations

LimitationWorkaround
Complex forms can’t render inline in Slack”Complete in Dashboard” button with deep link
Sensitive fields (passwords) can’t appear in SlackAlways routed to dashboard
Slack modals require additional scopesCurrently uses buttons only; modal support planned
Bot must be in the channelInvite the bot before testing

​
Security Considerations

  • Never expose the signing secret. Store it in a secrets manager, not in source code.
  • The bot token is sensitive. It allows posting to channels. Restrict it to the minimum required scopes.
  • Verify every inbound request. The signing secret verification prevents attackers from forging Slack payloads.
  • Svantic never sends sensitive field values to Slack. Credentials, passwords, and other sensitive A2UI fields are filtered out by the SlackRenderer.

​
Troubleshooting

ProblemCheck
No message in SlackIs the bot invited to the channel? Is the channel ID correct?
Buttons don’t workIs the Interactivity Request URL correct? Is it HTTPS?
”Invalid signature” errorsIs the signing secret in Svantic the same as in Slack’s Basic Information?
”Already resolved” after clickingSomeone else (dashboard/webhook) resolved it first
Test works but real notifications don’tCheck the event_filter — does it include input-required?

​
Further Reading