Discord Integration

Discord integration allows you to receive 9n9s alerts directly in your Discord channels with rich embeds, color coding, and role mentions for your community or team.

Quick Setup

Create Discord Webhook
- Go to your Discord server settings
- Navigate to Integrations → Webhooks
- Click “Create Webhook” or “New Webhook”
- Configure the webhook settings
Configure in 9n9s
- Go to Organization Settings > Notification Channels
- Click “Add Channel” → “Discord”
- Enter your webhook URL and customize settings
- Click “Create Channel”
Test Integration
- Click “Send Test Message”
- Verify message appears in Discord channel
- Check formatting and mentions

Prerequisites

Discord Server Requirements

Admin Permissions: You need “Manage Webhooks” permission in the Discord server
Channel Access: Target channel must allow webhook integrations
Server Type: Works with all Discord server types (community, private, etc.)

9n9s Requirements

Organization Admin: Admin role to configure notification channels
Active Subscription: Discord integration available on all plans

Setting Up Discord Webhook

Step 1: Create Webhook in Discord

Access Server Settings
- Right-click your Discord server name
- Select “Server Settings”
- Navigate to “Integrations” in the left sidebar
Create New Webhook
- Click “Webhooks” tab
- Click “Create Webhook” button
- This opens the webhook configuration
Configure Webhook
- Name: “9n9s Alerts” (or your preferred name)
- Channel: Select target channel (e.g., #alerts, #monitoring)
- Avatar: Upload 9n9s logo or custom image (optional)
Copy Webhook URL
- Click “Copy Webhook URL”
- Save this URL securely for 9n9s configuration

Step 2: Add Discord Channel in 9n9s

Navigate to Notification Channels
- Log into app.9n9s.com
- Go to Organization Settings
- Click “Notification Channels”
Create Discord Channel
- Click “Add Channel” button
- Select “Discord” from integration types
- Enter webhook configuration details
Channel Configuration
- Channel Name: “Discord Alerts” (internal reference)
- Webhook URL: Paste the Discord webhook URL
- Username: “9n9s Monitor” (appears as message sender)
- Avatar URL: Custom avatar URL (optional)

Step 3: Customize Message Format

Embed Configuration
- Rich Embeds: Enable Discord embed formatting
- Color Coding: Automatic colors based on alert severity
- Thumbnail: Include 9n9s logo or status indicators
- Footer: Add timestamp and monitor information
Mention Settings
- Role Mentions: Configure which roles to mention
- User Mentions: Specific user mentions for critical alerts
- @everyone/@here: Use sparingly for critical incidents only
- Mention Conditions: When to use mentions (critical only, all alerts, etc.)

Message Customization

Embed Structure

Discord messages use rich embeds with the following structure:

Critical Alert Example:

{
    "embeds": [
        {
            "title": "🚨 CRITICAL: API Health Check",
            "description": "Monitor is DOWN (was UP)",
            "color": 15158332,
            "fields": [
                {
                    "name": "Duration",
                    "value": "5 minutes",
                    "inline": true
                },
                {
                    "name": "Environment",
                    "value": "production",
                    "inline": true
                },
                {
                    "name": "Project",
                    "value": "Core Services",
                    "inline": true
                }
            ],
            "footer": {
                "text": "9n9s Monitoring",
                "icon_url": "https://9n9s.com/logo.png"
            },
            "timestamp": "2024-01-15T14:30:00Z"
        }
    ]
}

Color Coding

Embeds automatically use color coding based on alert severity:

🟢 Green (3066993): UP, Recovered, Resolved
🟡 Yellow (16776960): DEGRADED, Warning, Late
🔴 Red (15158332): DOWN, Critical, Failed
🔵 Blue (3447003): Maintenance, Scheduled
⚫ Gray (9807270): Paused, Unknown

Role Mentions

Configure role mentions for different alert types:

mention_config:
    critical_alerts:
        roles: ["@DevOps", "@On-Call"]
        conditions: ["status:DOWN", "criticality:high"]

    standard_alerts:
        roles: ["@Monitoring"]
        conditions: ["status:DEGRADED"]

    recovery_notifications:
        roles: [] # No mentions for recovery
        conditions: ["status:UP"]

Advanced Configuration

Alert Routing

Set up different Discord channels for different alert types:

Critical Alerts Channel
- Channel: #critical-alerts
- Mentions: @here for immediate attention
- Conditions: criticality=critical
General Alerts Channel
- Channel: #alerts
- Mentions: @Monitoring role
- Conditions: All other alerts
Team-Specific Channels
- Channel: #backend-alerts
- Mentions: @Backend role
- Conditions: team=backend

Custom Webhook Configuration

For advanced use cases, you can configure webhook details:

{
    "webhook_url": "https://discord.com/api/webhooks/...",
    "username": "9n9s Alerts",
    "avatar_url": "https://9n9s.com/assets/discord-avatar.png",
    "embeds": true,
    "rate_limit": {
        "messages_per_minute": 30,
        "burst_limit": 5
    },
    "retry_config": {
        "max_retries": 3,
        "retry_delay": "5s"
    }
}

Bot Integration (Alternative)

For more advanced features, you can create a Discord bot:

Create Discord Application
- Go to Discord Developer Portal
- Create new application
- Add bot to your server
Configure Bot Permissions
- Send Messages
- Embed Links
- Use Slash Commands (optional)
Integration Benefits
- Interactive buttons (acknowledge, snooze)
- Slash commands for status checks
- Enhanced permission control

Security and Best Practices

Webhook Security

URL Protection
- Keep webhook URLs confidential
- Regenerate if compromised
- Use HTTPS-only webhooks
Permission Management
- Limit webhook creation permissions
- Regular audit of active webhooks
- Remove unused webhooks promptly

Message Management

Rate Limiting
- Discord has rate limits (30 messages per minute)
- 9n9s automatically handles rate limiting
- Configure burst settings appropriately
Content Guidelines
- Follow Discord’s Terms of Service
- Avoid spam or excessive mentions
- Keep messages concise but informative

Troubleshooting

Common Issues

Messages Not Appearing:

Check Webhook URL
- Verify URL is correct and active
- Test webhook with Discord’s webhook tester
- Ensure webhook hasn’t been deleted
Permission Issues
- Verify bot/webhook has message permissions
- Check channel permissions
- Ensure server allows webhooks

Rate Limiting:

Too Many Messages
- Check 9n9s rate limiting settings
- Reduce alert frequency if needed
- Use message grouping features
Discord API Limits
- Discord limits: 30 messages per minute
- 9n9s automatically retries
- Consider using multiple webhooks for high volume

Formatting Issues:

Embed Not Displaying
- Verify embed is enabled in Discord channel
- Check JSON structure validity
- Test with simplified embed first

Error Codes

Common Discord API errors:

400 Bad Request: Invalid webhook payload
401 Unauthorized: Invalid webhook URL
404 Not Found: Webhook was deleted
429 Too Many Requests: Rate limit exceeded

Testing

Test your Discord integration:

# Test webhook manually
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Test message from 9n9s",
    "embeds": [{
      "title": "Test Alert",
      "description": "This is a test message",
      "color": 3447003
    }]
  }' \
  "YOUR_WEBHOOK_URL"

Best Practices

Channel Organization

Dedicated Channels
- Create specific channels for monitoring alerts
- Separate critical from informational alerts
- Use clear channel names (#9n9s-alerts, #monitoring)
Role Structure
- Create monitoring-specific roles
- Configure role permissions appropriately
- Use role mentions strategically

Message Design

Clear Information
- Include service name and environment
- Provide direct links to dashboards
- Use consistent formatting
Actionable Content
- Include troubleshooting links
- Provide escalation procedures
- Add relevant context and tags

Maintenance

Regular Reviews
- Test webhook functionality monthly
- Review and update role mentions
- Clean up unused webhooks
Documentation
- Document webhook purposes
- Maintain channel guidelines
- Keep emergency contact information updated

Discord integration provides an excellent way to keep your team informed about system health in a platform they’re already using. Configure multiple channels and role mentions to ensure the right people get notified about the right issues at the right time.