Skip to main content

Discord Integration

Send real-time alerts to Discord channels with rich embeds, role mentions, and thumbnails. Perfect for developer teams using Discord as their primary communication platform.

Prerequisites

  • Discord server with permissions to create webhooks
  • BlackTide account (any plan)
  • Access to Alerts → Alert Channels in BlackTide

Step 1: Create a Discord Webhook

  1. Open Discord and navigate to your server
  2. Right-click the channel where you want to receive alerts (e.g., #alerts)
  3. Click Edit Channel
  4. Go to Integrations tab
  5. Click Create Webhook
  6. Name your webhook (e.g., "BlackTide Alerts")
  7. Upload a custom avatar (optional, download BlackTide logo from here)
  8. Click Copy Webhook URL
  9. Save changes

Your webhook URL will look like: https://discord.com/api/webhooks/1234567890/abcdefghijklmnop...

Step 2: Configure BlackTide Discord Channel

  1. Log in to BlackTide
  2. Navigate to Alerts → Alert Channels
  3. Click New Channel
  4. Select Discord as the channel type
  5. Fill in the configuration:
    • Name: DevOps Discord (or descriptive name)
    • Webhook URL: Paste the URL from Step 1
    • Username: BlackTide Monitor (optional)
    • Avatar URL: https://blacktide.xyz/logo.png (optional)
    • Role Mentions: @Developers, @On-Call (optional)
  6. Click Test Channel to send a test message
  7. Verify the test message appears in your Discord channel
  8. Click Save

Configuration Example

{
  "type": "discord",
  "name": "DevOps Discord",
  "config": {
    "webhookUrl": "https://discord.com/api/webhooks/1234567890/abcdef...",
    "username": "BlackTide Monitor",
    "avatarUrl": "https://blacktide.xyz/logo.png",
    "roleMentions": ["@Developers", "@On-Call"],
    "embedColor": "#FF0000"
  }
}

Step 3: Create an Alert Rule

  1. Go to Alerts → Alert Rules
  2. Click New Rule
  3. Configure your rule:
    • Name: Production API Down
    • Monitors: Select monitors to watch
    • Conditions: 3 consecutive failures
    • Channels: Select your Discord channel
    • Notify on Recovery: Yes
  4. Save the rule

Message Format

Downtime Alert (Rich Embed)

BlackTide sends alerts as Discord rich embeds with color-coded sidebars:

🚨 Monitor Down

@Developers @On-Call

Monitor: Production API
URL: https://api.example.com/health
Status: Down
Region: US East
Failed Checks: 3 consecutive
Last Error: Connection timeout after 10s

Time: 2026-02-13 14:30:00 UTC

[View Monitor] [Dashboard]

Embed Colors

  • Down: Red (#FF0000)
  • Degraded: Yellow (#FFAA00)
  • Up/Recovered: Green (#00FF00)
  • Maintenance: Blue (#0000FF)

Advanced Features

1. Role Mentions

Notify specific Discord roles when alerts trigger:

{
  "roleMentions": [
    "@Developers",       // Notify Developers role
    "@On-Call",          // Notify On-Call role
    "@everyone"          // Notify entire server (use sparingly!)
  ]
}

How to Find Role IDs

For advanced usage with role IDs instead of names:

  1. Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode)
  2. Right-click a role in Server Settings → Roles
  3. Click Copy ID
  4. Use <@&ROLE_ID> in mentions

2. Custom Embed Fields

Add custom fields to embeds:

{
  "customFields": [
    { "name": "Severity", "value": "P0", "inline": true },
    { "name": "Team", "value": "Backend", "inline": true },
    { "name": "Runbook", "value": "[Link](https://wiki.example.com/runbooks/api-down)", "inline": false }
  ]
}

3. Thumbnail Images

Show monitor type icons in embeds:

  • HTTP Monitor: Globe icon
  • TCP Monitor: Port icon
  • Web3 Monitor: Blockchain icon

4. Footer with Timestamp

All embeds include:

  • BlackTide logo in footer
  • Timestamp (automatically formatted by Discord)
  • Monitor ID for tracking

Best Practices

1. Separate Channels by Environment

Create different Discord channels for different alert types:

  • #alerts-production: Critical production issues
  • #alerts-staging: Staging environment alerts
  • #alerts-web3: Web3-specific notifications
  • #alerts-performance: Latency and performance alerts

2. Use Role Mentions Wisely

Avoid spamming @everyone:

  • P0 (Critical): @On-Call or @Developers
  • P1 (High): @Developers
  • P2-P3: No mentions

3. Customize Embed Colors by Severity

// P0 (Critical) - Red
"embedColor": "#FF0000"

// P1 (High) - Orange
"embedColor": "#FF6600"

// P2 (Medium) - Yellow
"embedColor": "#FFAA00"

// P3 (Low) - Blue
"embedColor": "#0099FF"

4. Test Webhooks Regularly

Discord webhooks can break if:

  • Webhook is deleted in Discord
  • Channel is deleted
  • Server is deleted
  • Bot loses permissions

Test your Discord channels monthly to ensure they still work.

5. Combine with Other Channels

Use Discord alongside other notification methods:

  • Primary: Discord (team visibility)
  • Backup: Email (reaches everyone)
  • Critical: PagerDuty/Opsgenie (on-call)

Troubleshooting

Test Message Not Appearing in Discord

Possible Causes:

  • Webhook URL is incorrect
  • Webhook was deleted
  • Discord channel was deleted
  • Permissions changed

Solution:

  1. Verify webhook URL is correct (starts with https://discord.com/api/webhooks/)
  2. Test webhook manually with curl:
    curl -X POST -H 'Content-Type: application/json' \
  -d '{"content":"Test from BlackTide"}' \
  YOUR_WEBHOOK_URL
  3. Recreate webhook if it was deleted
  4. Check Discord channel still exists

Role Mentions Not Working

Possible Causes:

  • Role doesn't exist
  • Role name misspelled
  • Role is not mentionable

Solution:

  1. Verify role exists in Server Settings → Roles
  2. Enable Allow anyone to @mention this role in role settings
  3. Use exact role name including capitalization

Embeds Not Showing Correctly

Solution:

Ensure your Discord client has embeds enabled:

  1. User Settings → Text & Images
  2. Enable Show website preview info from links pasted into chat
  3. Enable Show embeds and preview website links pasted into chat

Security Considerations

Webhook URL Security

  • Treat webhook URLs as secrets (anyone with the URL can post to your channel)
  • Don't commit webhook URLs to version control
  • Rotate webhooks if they're accidentally exposed
  • Consider using private Discord channels for sensitive alerts

Sensitive Data in Alerts

  • Don't include API keys, passwords, or tokens in monitor names
  • Mask sensitive data in alert messages
  • Use private channels for alerts containing PII

Rate Limits

Discord has rate limits for webhook messages:

  • Discord API Limit: 5 messages per second per webhook
  • Burst Limit: 30 messages per minute
  • BlackTide Limit: 20 alerts per hour per channel

If you hit the BlackTide rate limit, alerts are queued and sent when the window resets.

Webhook Payload Example

For advanced users wanting to customize webhooks, here's the payload BlackTide sends:

{
  "username": "BlackTide Monitor",
  "avatar_url": "https://blacktide.xyz/logo.png",
  "content": "@Developers Monitor down!",
  "embeds": [
    {
      "title": "🚨 Production API - Down",
      "description": "Monitor has failed 3 consecutive checks",
      "color": 16711680,
      "fields": [
        { "name": "URL", "value": "https://api.example.com/health", "inline": false },
        { "name": "Region", "value": "US East", "inline": true },
        { "name": "Status", "value": "Down", "inline": true },
        { "name": "Error", "value": "Connection timeout after 10s", "inline": false }
      ],
      "thumbnail": {
        "url": "https://blacktide.xyz/icons/monitor-down.png"
      },
      "footer": {
        "text": "BlackTide • Monitor ID: mon_abc123",
        "icon_url": "https://blacktide.xyz/logo-small.png"
      },
      "timestamp": "2026-02-13T14:30:00.000Z"
    }
  ]
}

Next Steps