Notifications

Notifications

Lumos Gate sends real-time alerts when important events happen across your infrastructure. Notifications are delivered via email, webhook, or both, depending on your configuration. There are 8 alert types covering server health, SSL certificates, DNS failover, and billing.

Alert Types

Server Alerts

server_down is triggered immediately when the agent's WebSocket connection drops -- there is no delay or debounce. The WebSocket server detects the disconnection the moment the TCP connection closes and dispatches the notification right away. Additionally, the 5-minute maintenance cycle runs a stale check as a safety net, catching any servers that have been unseen for more than 120 seconds but were not caught by the WebSocket disconnect event.

The notification includes:

• Server name and server ID
• Timestamp of disconnection

server_recovered is sent when a previously offline agent reconnects to the WebSocket server and is confirmed healthy.

The notification includes:

• Server name and server ID
• Timestamp of recovery

server_error covers three distinct error scenarios reported by the agent:

The notification includes:

• Server name and server ID
• Error sub-type
• Error message from the agent

Tip: Occasional server_error alerts are normal -- the agent recovers automatically from all three scenarios. However, repeated errors from the same server indicate an underlying issue (disk full, corrupted binary, network instability) that needs manual investigation. See Troubleshooting.

SSL Alerts

ssl_expiring is checked during the health check cycle (every 5 minutes via the WebSocket server maintenance loop). The system queries all domains that have SSL enabled and checks if any certificate's expiry date is within 7 days. To avoid alert fatigue, this notification is sent at most once per 24 hours per domain.

The notification includes:

• Domain name
• Number of days until expiry
• Expiry date (ISO 8601)

Warning: If you receive an ssl_expiring alert, it means auto-renewal has not yet succeeded for that domain. The agent will continue attempting ACME HTTP-01 renewal automatically, but you should verify that port 80 is accessible on the shield server and that the domain still points to the correct IP. See SSL/TLS for troubleshooting.

ssl_renewed is sent when the agent reports a successful certificate renewal via the ssl.status WebSocket message. This is purely informational and is disabled by default.

The notification includes:

• Domain name

Failover Alerts

Sent when the DNS Failover system detects a primary server is down and switches the DNS A record to a secondary server's IP via the Cloudflare API. A corresponding recovery notification uses the server_recovered alert type when DNS is switched back to the primary.

The notification includes:

• Domain name
• Source IP (the failed primary)
• Target IP (the healthy secondary)

Note: Failover requires multiple servers assigned to the domain and a configured DNS provider. Without these, the failover_triggered alert will never fire even if a server goes down.

Billing Alerts

low_balance is checked during each billing deduction cycle (every 5 minutes, triggered by the WebSocket server maintenance loop). If your remaining credit balance is less than twice your plan's price, this warning is sent so you have time to deposit before the account is frozen.

The notification includes:

• Current balance
• Plan price

account_frozen is sent when a billing deduction fails because the balance is insufficient. The account enters frozen mode, which blocks all mutation operations (creating/editing servers, domains, WAF rules, etc.) in the dashboard. Read-only operations like viewing analytics and exporting configuration still work.

The notification includes:

• Current balance
• Amount that was due

Important: To unfreeze your account, deposit enough credits to cover at least one billing cycle. The system automatically unfreezes the account when a deposit brings the balance above the plan price. See Credits & Billing for deposit instructions.

Delivery Channels

Email

Email notifications are delivered via a reliable email service. Each alert type generates a formatted HTML email with:

• Alert type and severity (color-coded: red for critical, amber for warning, green for recovery/info)
• Contextual title (server name, domain name, etc.)
• Actionable description of the event
• Timestamp
• Lumos Gate branding footer

All dynamic content in email templates is properly escaped to prevent XSS injection.

The email is sent to the address configured in your notification settings. By default this is your account email, but you can change it to a team distribution list or ops email address.

Webhook

Webhooks allow you to integrate Lumos Gate alerts with any external system -- Slack, Discord, PagerDuty, Opsgenie, custom monitoring dashboards, or your own automation scripts.

Webhook notifications are sent as HTTP POST requests with a JSON body:

{
  "type": "server_down",
  "title": "EU Frankfurt",
  "message": "Server 'EU Frankfurt' is offline",
  "timestamp": "2026-02-20T14:30:00.000Z",
  "serverId": "srv_abc123"
}

For domain-specific alerts (SSL, failover), additional metadata fields are included:

{
  "type": "failover_triggered",
  "title": "example.com",
  "message": "DNS failover triggered for example.com. Traffic moved from 1.2.3.4 to 5.6.7.8.",
  "timestamp": "2026-02-20T14:35:00.000Z",
  "fromIp": "1.2.3.4",
  "toIp": "5.6.7.8"
}

{
  "type": "ssl_expiring",
  "title": "example.com",
  "message": "SSL certificate for example.com expires in 5 days. Auto-renewal will be attempted.",
  "timestamp": "2026-02-20T14:40:00.000Z",
  "daysLeft": 5,
  "expiresAt": "2026-02-25T00:00:00.000Z"
}

Webhook requests have a 10-second timeout. If your endpoint does not respond within 10 seconds, the delivery is considered failed. Failed webhook deliveries are logged but not retried.

Warning: Webhook URLs pointing to private/reserved IP ranges are blocked as an SSRF protection measure. This includes localhost, 127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x, 0.0.0.0, and IPv6 link-local (fe80:). Your webhook endpoint must be publicly accessible.

Integrating with Slack

To send alerts to a Slack channel:

1. Go to api.slack.com/messaging/webhooks and create an Incoming Webhook
2. Select the channel where alerts should appear
3. Copy the webhook URL (starts with https://hooks.slack.com/services/...)
4. Paste it in Dashboard -> Settings -> Notifications -> Webhook URL

Slack will display the JSON payload as a formatted message. For richer formatting (attachments, colors), consider routing through a middleware like Zapier or n8n that transforms the payload into Slack Block Kit format.

Integrating with Discord

To send alerts to a Discord channel:

1. In Discord, go to Channel Settings -> Integrations -> Webhooks -> New Webhook
2. Name it (e.g., "Lumos Alerts") and copy the URL
3. Paste it in Dashboard -> Settings -> Notifications -> Webhook URL

Discord expects a specific payload format for rich embeds. Lumos Gate sends standard JSON, which Discord will display as raw text. For formatted embeds, use a middleware service or a Discord bot that parses the incoming webhook.

Configuration

Navigate to Dashboard -> Settings -> Notifications to configure your alert preferences.

Enable/Disable Individual Alerts

Each of the 8 alert types can be toggled independently for email delivery. For example, you might want server_down and account_frozen alerts but not ssl_renewed (which is purely informational).

Default settings for new accounts:

Note: The server_error alert shares the same email toggle as server_down. If you enable server_down emails, you also get server_error emails. This is by design since both indicate server-level issues that require attention.

Webhook Settings

Enter a webhook URL to receive all enabled alert types as HTTP POST requests. The webhook toggle is separate from individual email toggles -- when enabled, all alert types are sent to the webhook URL regardless of individual email settings.

Example webhook URLs:
  https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  https://discord.com/api/webhooks/000000000000000000/XXXXXXXXXXXXXXXXXXXX
  https://your-api.example.com/webhooks/lumos-alerts

Notification Flow (Internal)

For those interested in the technical implementation, the internal notification pipeline works as follows:

Event Source                        Routing                          Delivery
-----------                         -------                          --------
Agent disconnects              ->   WebSocket server detects     ->  Notification dispatch
HAProxy crash / reload fail    ->   Agent reports via WebSocket  ->  Notification dispatch
Health check (5-min cycle)     ->   WebSocket server triggers    ->  Notification dispatch
Billing deduction              ->   WebSocket server triggers    ->  Notification dispatch
                                         |
                                         v
                                  Notification dispatch:
                                    1. Load notification settings
                                    2. Check alert type enabled
                                    3. Send email
                                    4. POST webhook (JSON)

The notification dispatcher is the single entry point for all notification delivery. It:

1. Loads the user's notification settings from the database
2. Checks whether email is enabled for the specific alert type
3. If enabled, renders the email from a template and sends it
4. If webhook is enabled, constructs the JSON payload and POSTs it to the configured URL (with SSRF protection and 10-second timeout)

Note: The notification and health check endpoints are internal-only and protected by a shared secret. They are not part of the public API and cannot be called with API keys.

Best Practices

• Always enable server_down and account_frozen -- These are the most critical alerts. A server going offline means traffic may be disrupted, and a frozen account means all management operations are blocked.
• Set up both email and webhook -- Email is reliable for async notification and creates a searchable archive. Webhooks reach Slack/Discord channels where your team is actively working and can respond faster.
• Act on low_balance promptly -- This gives you advance warning before the account freezes. Deposit credits when you receive this alert to avoid service interruption.
• Review server_error alerts -- While the agent auto-recovers from most errors (restarts HAProxy, rolls back bad configs), repeated errors from the same server indicate an underlying issue that needs attention.
• Do not ignore ssl_expiring -- If auto-renewal is failing, you have 7 days to fix the issue before the certificate expires and your site starts showing browser warnings. Check that port 80 is open and DNS points to the shield server.
• Test your webhook endpoint -- After configuring a webhook, stop an agent temporarily to trigger a server_down alert and verify the webhook payload arrives correctly.

Next Steps

• DNS Failover -- Set up automatic failover (generates failover_triggered alerts)
• SSL/TLS -- Understand certificate provisioning and renewal (generates SSL alerts)
• Credits & Billing -- Understand the billing cycle, frozen accounts, and deposit flow
• Multiple Servers -- Add redundant servers (generates per-server alerts)
• Account -- Manage notification email address and account settings
• Troubleshooting -- Debug common issues flagged by notifications