Discord Integration

Receive real-time notifications about bans, syncs, and errors in Discord.

Setup

1. Create Discord Webhook

1. Open Discord and go to your server
2. Right-click the channel for notifications
3. Select Edit Channel → Integrations
4. Click Create Webhook
5. Name the webhook (e.g., "Bloqd Alerts")
6. Copy the Webhook URL

2. Configure in Bloqd

1. Go to Settings → Discord
2. Enable Discord integration
3. Paste the webhook URL
4. Configure notification options
5. Click Test Connection
6. Click Save

Or via environment variables:

DISCORD_ENABLED=true
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
DISCORD_NOTIFY_BANS=true
DISCORD_NOTIFY_SYNCS=true
DISCORD_NOTIFY_ERRORS=true
DISCORD_DAILY_SUMMARY=true
DISCORD_DAILY_SUMMARY_HOUR=8

Notification Types

Ban Notifications

Sent when an IP is banned.

Field	Description
IP Address	Banned IP with country flag
Jail	Which jail triggered the ban
Server	Server hostname
Log Excerpt	Relevant log lines
Timestamp	When the ban occurred

Color: Red

Sync Notifications

Sent when whitelist syncs complete.

Field	Description
Server	Server hostname
Status	Success or failure
Changes	Number of entries added/removed

Color: Green (success) or Orange (failed)

Error Notifications

Sent when errors occur.

Field	Description
Error Type	Category of error
Message	Error details
Server	Affected server (if applicable)

Color: Orange

Daily Summary

Aggregated report sent once per day.

Field	Description
Total Bans	Bans in last 24 hours
Top Countries	Countries with most bans
Top Jails	Jails with most activity
Server Status	Health of all servers

Color: Purple

Configuration Options

Option	Description	Default
Notify Bans	Send message for each ban	On
Notify Syncs	Send message for sync events	On
Notify Errors	Send message for errors	On
Daily Summary	Send aggregated daily report	On
Summary Hour	Hour (UTC) for daily summary	8

Message Format

Ban Alert Example

🔴 IP Banned

IP: 192.168.1.100 🇨🇳
Jail: sshd
Server: web-server-01
Time: 2024-01-15 10:30:00 UTC

Log:
Failed password for root from 192.168.1.100 port 22 ssh2

Daily Summary Example

🟣 Daily Summary - 2024-01-15

📊 Last 24 Hours:
• 247 bans across 5 servers
• 89 unique IPs

🌍 Top Countries:
1. 🇨🇳 China (45%)
2. 🇷🇺 Russia (23%)
3. 🇺🇸 United States (12%)

📋 Top Jails:
1. sshd (156)
2. nginx-botsearch (52)
3. postfix-sasl (39)

✅ All servers healthy

Multiple Channels

To send different notifications to different channels:

1. Create multiple webhooks in Discord
2. In Bloqd, you can configure per-notification webhooks via API
3. Or use a Discord bot for more advanced routing

Rate Limiting

Discord webhooks have rate limits:

• 30 messages per minute
• 5 webhooks per channel

Bloqd automatically:

• Batches rapid bans
• Queues messages during rate limits
• Skips duplicate notifications

Testing

Test Connection

1. Go to Settings → Discord
2. Click Test Connection
3. Check Discord for test message

Manual Test

curl -X POST "https://bloqd.example.com/api/v1/settings/discord/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting

No Messages Received

1. Verify webhook URL is correct
2. Check Discord channel permissions
3. Verify Bloqd Discord is enabled
4. Check server logs for errors

Webhook Invalid

Discord Error: Invalid webhook URL

1. Regenerate webhook in Discord
2. Update URL in Bloqd settings

Rate Limited

Discord Error: Rate limited

• Messages are queued automatically
• Consider reducing notification types
• Use daily summary instead of per-ban alerts

Security

• Webhook URL is sensitive - don't share it
• Use a private channel for security alerts
• Consider separate webhook for testing