Slack & Teams Notifications¶

ARX integrates with Slack and Microsoft Teams to deliver real-time notifications for approval requests, drift alerts, and agent status changes. This guide covers configuring notification channels, supported event types, interactive approval buttons, webhook handlers, and Slack signature verification.

Supported Platforms¶

Configuring Notification Channels¶

All notification channel endpoints require the admin role and are accessed under /v1/settings/notifications.

List Channels¶

GET /v1/settings/notifications

Returns all configured notification channels for the organization.

Create a Channel¶

POST /v1/settings/notifications

Update a Channel¶

PUT /v1/settings/notifications/{channel_id}

Delete a Channel¶

DELETE /v1/settings/notifications/{channel_id}

Test a Channel¶

POST /v1/settings/notifications/{channel_id}/test

{
  "message": "This is a test notification from ARXsec."
}

Configuring Slack¶

Option 1: Bot Token (Recommended)¶

Bot tokens provide richer functionality, including interactive messages and the ability to post to multiple channels.

1. Create a Slack App at api.slack.com/apps.
2. Under OAuth & Permissions, add the following bot scopes:
3. chat:write -- post messages
4. chat:write.public -- post to channels the bot hasn't joined
5. Install the app to your workspace and copy the Bot User OAuth Token (xoxb-...).
6. Note the Channel ID of the target channel (right-click the channel name in Slack and select "Copy link" -- the ID is in the URL).

{
  "channel_type": "slack",
  "name": "Security Alerts",
  "config": {
    "bot_token": "xoxb-your-bot-token",
    "channel_id": "C0123456789"
  },
  "events": ["approval_request", "drift_alert", "agent_status"]
}

Option 2: Incoming Webhook¶

Incoming webhooks are simpler to set up but do not support interactive messages (approve/deny buttons).

1. In your Slack workspace, navigate to Apps > Incoming Webhooks (or create a Slack App with incoming webhooks enabled).
2. Create a webhook for the target channel and copy the webhook URL.

{
  "channel_type": "slack",
  "name": "Alerts Webhook",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX"
  },
  "events": ["drift_alert", "agent_status"]
}

Note: At least one of bot_token + channel_id or webhook_url is required. If neither is provided, the channel creation request is rejected.

Configuring Microsoft Teams¶

Incoming Webhook¶

1. In Microsoft Teams, navigate to the target channel.
2. Click the ... menu next to the channel name and select Connectors (or Manage channel > Connectors).
3. Find Incoming Webhook and click Configure.
4. Name the webhook (e.g., "ARX Notifications") and copy the webhook URL.

{
  "channel_type": "teams",
  "name": "Teams Security Alerts",
  "config": {
    "webhook_url": "https://outlook.office.com/webhook/..."
  },
  "events": ["approval_request", "drift_alert", "agent_status"]
}

A webhook_url is required for Teams channels.

Event Types¶

Configure which events a channel receives using the events array. By default, new channels receive all three event types.

Interactive Approval Buttons¶

When an approval_request notification is sent to Slack (via bot token) or Teams, the message includes interactive approve/deny buttons. Reviewers can approve or deny the request directly from the messaging platform without opening the ARX console.

How It Works¶

1. ARX sends a notification with approve and deny buttons attached.
2. The reviewer clicks a button.
3. Slack or Teams sends a callback to the ARX webhook endpoint.
4. ARX processes the decision using the same validation logic as the REST API:
5. Checks if the approval request is still pending (not already reviewed).
6. Checks if the approval request has expired.
7. Records the decision with the reviewer's name and source (Slack or Teams).
8. Logs the action in the audit trail.
9. The original message is replaced with the decision result.

Webhook Handlers¶

Slack Interactions¶

POST /v1/webhooks/slack/interactions

Slack sends interactive message callbacks as a URL-encoded payload field. ARX processes the following action IDs:

After processing, ARX returns a replacement message showing the decision result:

• Approved: :white_check_mark: **APPROVED** by <username>
• Denied: :x: **DENIED** by <username>
• Error: :warning: <error message> (e.g., "Already approved", "Approval request has expired")

Teams Interactions¶

POST /v1/webhooks/teams/interactions

Teams sends adaptive card Action.Submit callbacks as JSON. The action data includes:

After processing, ARX returns an updated Adaptive Card showing the decision result with appropriate color coding (green for approved, red for denied).

Slack Signature Verification¶

When SLACK_SIGNING_SECRET is configured, ARX verifies the authenticity of incoming Slack webhook requests using Slack's v0 signing scheme:

1. ARX reads the X-Slack-Request-Timestamp and X-Slack-Signature headers.
2. If the timestamp is more than 5 minutes old, the request is rejected (replay protection).
3. ARX computes v0:<timestamp>:<body> and generates an HMAC-SHA256 signature using the signing secret.
4. The computed signature is compared against the provided X-Slack-Signature using constant-time comparison.
5. If the signatures do not match, the request is rejected with 401 Unauthorized.

Set the signing secret via environment variable:

SLACK_SIGNING_SECRET=your-slack-signing-secret

The signing secret is found on your Slack App's Basic Information page under App Credentials.

Approval Processing Logic¶

Both Slack and Teams handlers route through a shared approval processing function that enforces:

1. Existence check: Returns an error if the approval request is not found.
2. Status guard: Returns an error if the request has already been reviewed.
3. Expiry check: If the request has expired, it is marked as expired and an error is returned.
4. Decision recording: The status is updated to approved or denied, with the reviewer's name and source recorded in review_notes.
5. Audit logging: The decision is logged with the approval.reviewed action type, including the risk score, reviewer name, and source platform.

Troubleshooting¶

Related Documentation¶

• Authentication Overview
• RBAC & Roles
• Webhook Configuration
• SIEM Export