Managing Alerts

1. Creating Alerts (Pro+ License)

Administrators with the alerts:create permission can create alerts via:

• The admin API: POST /api/admin/alerts
• Plugins with the alerts:create permission

Required Fields

Optional Fields

Example: Create a Broadcast Alert

curl -X POST /api/admin/alerts \
  -H "Content-Type: application/json" \
  -d '{
    "category": "system",
    "severity": "warning",
    "targetType": "broadcast",
    "title": "Scheduled Maintenance",
    "message": "System will be down for maintenance at 02:00 UTC tonight.",
    "actions": [{"label": "View Details", "url": "/maintenance/upcoming"}]
  }'

Example: Target Specific Roles

curl -X POST /api/admin/alerts \
  -H "Content-Type: application/json" \
  -d '{
    "category": "deployment",
    "severity": "info",
    "targetType": "role",
    "targetValue": ["developer", "devops"],
    "title": "New Release v2.1.0",
    "message": "Version 2.1.0 has been deployed successfully."
  }'

2. Forced Categories (Enterprise License)

Administrators with the alerts:admin permission can configure forced categories — categories that users cannot mute.

Managing Forced Categories

Access the Forced Categories panel in the admin settings. From there you can:

• View the current list of forced categories
• Add new categories (type the name and click "Add" or press Enter)
• Remove categories (click the X button)
• Save changes (click "Save Changes")

When to Use Forced Categories

Use forced categories for notifications that all users must receive regardless of their preferences:

• Security alerts
• Compliance notifications
• Critical system announcements
• Billing/payment issues

API

# Get current forced categories
GET /api/admin/alerts/config

# Update forced categories
PUT /api/admin/alerts/config
{
  "forcedCategories": ["security", "compliance", "billing"]
}

3. Viewing All Alerts (Enterprise License)

Administrators with the alerts:admin permission can view all alerts system-wide:

GET /api/admin/alerts?category=system&severity=critical&limit=50

This returns all alerts regardless of targeting, with optional filtering by category, severity, and target type.

4. Scheduler Health Alerts

The system monitors background jobs. When a scheduled job fails several times in a row (3 by default, set with SCHEDULER_UNHEALTHY_THRESHOLD), super admins and organization admins get an alert, shown in each person's language:

• Job failing (critical) — "Job cleanup is failing", with the number of failures and the last error
• Job recovered (info) — when the job succeeds again

Both link to Settings → Advanced → Scheduled Jobs. They are built-in automation rules: super admins can change who gets them or switch them off under Settings → Automation. Each job has its own category ("Scheduled job: <name>"), so a job's recovery replaces its own failure alert and doesn't hide other jobs' alerts. Muting that category mutes that one job's health alerts.

5. Backup Alerts

When a backup can't be written or fails its integrity check, super admins get a critical alert ("The scheduled backup failed its integrity check (checksum_mismatch). Open Settings → Backups for details."). See Backups.

6. Automatic Cleanup

Alerts are automatically cleaned up based on their state:

These defaults can be configured via environment variables. The cleanup job runs daily at 02:00 by default and can be managed from the Scheduler UI.

7. Audit Trail

All administrative alert actions are audit logged:

• Alert creation (who created it, what was the payload)
• Forced categories changes (before/after state)

Audit logs are accessible to Enterprise-tier administrators via the audit log viewer.

8. API Reference

User Endpoints

Admin Endpoints

Pagination

All list endpoints use cursor-based pagination:

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJ2Ijp...",
    "prevCursor": "",
    "hasNext": true,
    "hasPrev": false,
    "limit": 20
  }
}

Pass ?cursor=<nextCursor>&limit=20 to fetch the next page.

Error Responses

Preferences Request Body

{
  "optedOut": false,
  "mutedCategories": ["marketing", "tips"]
}

9. WebSocket Connection

Connect to /api/ws for real-time notifications. Authentication uses your session cookie (same as REST API).

Message Format

All messages use a JSON envelope:

{
  "type": "alert.new",
  "payload": { ... },
  "timestamp": "2026-06-01T10:00:00.123Z"
}

Message Types

Reconnection

If the WebSocket connection drops, the client automatically reconnects with exponential backoff (1s, 2s, 4s, ... up to 30s max). On reconnect, the server sends a fresh alert.init message to catch up on any missed notifications.