Slack Integration

The Slack integration provides a powerful admin interface for Heimdall, allowing administrators to monitor and manage the system directly from Slack. This integration is platform-agnostic and works across all SDK implementations.

Features

Event Notifications

The integration can send real-time notifications for various system events to a configured Slack channel.

Available Events

type EventType =
  | 'user.signup'
  | 'user.login'
  | 'user.logout'
  | 'user.ban'
  | 'user.unban'
  | 'team.create'
  | 'team.delete'
  | 'role.assign'
  | 'role.remove'
  | 'permission.grant'
  | 'permission.revoke'
  | 'security.alert'
  | 'system.error'

type EventSeverity = 'info' | 'warning' | 'error' | 'critical'

Event Configuration

Events can be configured using environment variables:

# Enable specific event types
HEIMDALL_SLACK_EVENTS=user.signup,user.login,security.alert

# Set minimum severity level
HEIMDALL_SLACK_MIN_SEVERITY=warning

# Configure webhook URL
HEIMDALL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Slash Commands

The integration provides several slash commands for administrative tasks:

User Management

• /heimdall ban <user> - Ban a user
• /heimdall unban <user> - Unban a user
• /heimdall user <user> - Get user information
• /heimdall users - List recent users

Organization Management

• /heimdall org <org> - Get organization information
• /heimdall orgs - List organizations
• /heimdall org-delete <org> - Delete an organization

Team Management

• /heimdall team <team> - Get team information
• /heimdall teams - List teams in an organization
• /heimdall team-delete <team> - Delete a team

Role Management

• /heimdall role <user> <role> - Assign a role to a user
• /heimdall role-remove <user> <role> - Remove a role from a user
• /heimdall roles - List available roles

Analytics Queries

The integration supports various analytics queries to get insights about system usage:

Time-based Queries

• /heimdall stats logins <period> - Get login statistics
  • Example: /heimdall stats logins 24h
  • Example: /heimdall stats logins 7d
  • Example: /heimdall stats logins 30d

Geographic Queries

• /heimdall stats region <region> - Get statistics for a specific region
• /heimdall stats country <country> - Get statistics for a specific country

User Activity

• /heimdall stats active-users <period> - Get active user statistics
• /heimdall stats new-users <period> - Get new user statistics

Message Formatting

The integration supports different message types and formatting:

Message Types

interface SlackMessage {
  type: 'info' | 'warning' | 'error' | 'success'
  title: string
  text: string
  fields?: {
    title: string
    value: string
    short: boolean
  }[]
  actions?: {
    name: string
    text: string
    type: 'button'
    value: string
  }[]
}

Example Messages

User Signup

{
  "type": "info",
  "title": "New User Signup",
  "text": "A new user has signed up",
  "fields": [
    {
      "title": "User",
      "value": "john.doe@example.com",
      "short": true
    },
    {
      "title": "Time",
      "value": "2024-03-20T10:30:00Z",
      "short": true
    }
  ]
}

Security Alert

{
  "type": "warning",
  "title": "Security Alert",
  "text": "Multiple failed login attempts detected",
  "fields": [
    {
      "title": "User",
      "value": "john.doe@example.com",
      "short": true
    },
    {
      "title": "IP Address",
      "value": "192.168.1.1",
      "short": true
    },
    {
      "title": "Attempts",
      "value": "5",
      "short": true
    }
  ],
  "actions": [
    {
      "name": "ban",
      "text": "Ban User",
      "type": "button",
      "value": "john.doe@example.com"
    }
  ]
}

Setup

1. Create a Slack App in your workspace
2. Configure the necessary permissions:
   • chat:write
   • commands
   • incoming-webhook
3. Set up the environment variables
4. Deploy the webhook endpoint
5. Install the app to your workspace

Security Considerations

• All webhook requests are signed and verified
• Commands require appropriate permissions
• Sensitive data is redacted in notifications
• Rate limiting is applied to all commands
• Audit logging is enabled for all administrative actions

Future Enhancements

• Interactive message buttons for common actions
• Custom command creation
• Scheduled reports
• Custom notification rules
• Integration with other communication platforms