DitDashDot's alert system monitors your services and sends notifications when they go down or come back online. The system works seamlessly with the Service Status theme mode to provide visual and automated notifications.

Prerequisites

Service Status Theme: Alert functionality requires the dashboard to be set to "Service Status Mode"
Service Monitoring: Services must have IP addresses and ports configured for monitoring
Webhook URL: A Discord webhook URL or compatible webhook endpoint for notifications

Setting Up Alerts

1. Enable Service Status Mode

Go to /config in your dashboard
Click on "General Settings" tab
Set Theme Mode to "Service Status Mode"
Save settings

2. Configure Alert Settings

Go to /config in your dashboard
Click on "Alerts" tab
Configure the following:

Global Alert Settings

Enable Alerts: Toggle alerts on/off globally
Down Threshold: How long services must be down before alerting (default: 5 minutes)

Webhook Configuration

Enable Webhook Notifications: Toggle webhook alerts on/off
Discord Webhook URL: Your Discord webhook URL (see Discord setup below)
Test Webhook: Button to send a test alert to verify configuration

3. Discord Webhook Setup

In Discord, go to your server
Right-click on the channel where you want alerts
Select "Edit Channel" → "Integrations" → "Webhooks"
Click "New Webhook"
Give it a name (e.g., "DitDashDot Alerts")
Copy the webhook URL
Paste the URL into the DitDashDot alert configuration

4. Per-Service Configuration

Each service can have individual alert settings:

Go to /config → "Services" tab
Edit a service
In the Alert Settings section:
- Enable alerts for this service: Override global enable/disable
- Down Threshold: Override global threshold for this specific service

Alert Features

Alert Types

Service Down: Sent when a service has been unreachable for the configured threshold
Service Recovery: Sent immediately when a service comes back online

Alert Pausing

Temporarily pause alerts during maintenance:

1 Hour: Quick maintenance window
4 Hours: Extended maintenance
24 Hours: Major maintenance or planned downtime

Alert History

View complete alert history including:

Service name and location (IP:Port)
Alert type (down/recovery)
Timestamp
Webhook delivery status

Example Alert Messages

Service Down Alert

🔴 Service "Plex Media Server" has been down for 5 minutes!
Service: Plex Media Server
Status: 🔴 Down
Location: 192.168.1.100:32400

Service Recovery Alert

🟢 Service "Plex Media Server" is back online!
Service: Plex Media Server
Status: 🟢 Up
Location: 192.168.1.100:32400

Troubleshooting

Alerts Not Working

Verify Service Status Mode is enabled
Check that services have IP addresses and ports configured
Ensure alert system is enabled in alert settings

Webhooks Not Delivering

Use the "Test Webhook" button to verify configuration
Check webhook URL is correct and active
Verify Discord channel permissions allow webhook messages

Too Many/Few Alerts

Adjust the down threshold (higher = fewer alerts, lower = more sensitive)
Use per-service thresholds for critical vs non-critical services
Use alert pausing during maintenance windows

Best Practices

Start Conservative: Begin with a 5-10 minute threshold to avoid false positives
Use Per-Service Settings: Set shorter thresholds for critical services
Test Configuration: Always use the test webhook feature before relying on alerts
Plan for Maintenance: Use alert pausing during planned downtime
Monitor Alert History: Review alert patterns to optimize thresholds

Advanced Configuration

Custom Webhook Formats

While designed for Discord, the webhook system sends JSON with the following structure:

{
  "username": "DitDashDot",
  "content": "Alert message",
  "embeds": [{
    "title": "Service Alert: Service Name",
    "description": "Detailed message",
    "color": 15158332,  // Red for down, green for up
    "fields": [
      {"name": "Service", "value": "Service Name", "inline": true},
      {"name": "Status", "value": "🔴 Down", "inline": true},
      {"name": "Location", "value": "192.168.1.100:32400", "inline": true}
    ],
    "timestamp": "2025-10-08T10:30:00Z"
  }]
}

This format is compatible with Discord and many other webhook services.

Need Help?

If you encounter issues with the alert system, see TROUBLESHOOTING.md for detailed troubleshooting steps.