Alerts

Alerts notify you when something goes wrong or when resource thresholds are reached. Configure alert rules from your dashboard to receive email notifications and HTTP callbacks in real-time.

Overview

The alerts system monitors two categories of events:

• Operational alerts detect errors during bot operations — failed joins, recording failures, crashes, and more
• Threshold alerts monitor resource metrics like token balance, daily bot usage, and calendar connections

Each alert rule defines what to monitor, when to trigger, how to notify you, and how often.

Creating an Alert Rule

Navigate to Alerts in your dashboard to create a new rule. Each rule requires:

1. Alert type — what to monitor (see Alert Types below)
2. Threshold — the value that triggers the alert
3. Delivery channels — where to send notifications (email, callback, or both)
4. Cooldown — minimum time between consecutive alerts (1–1440 minutes, default: 15 minutes)

At least one delivery channel (email or callback) is required.

Alert Types

Operational Alerts

Operational alerts count error occurrences and fire when the count reaches your configured threshold. The same cooldown window is used for both counting events and suppressing repeated alerts after delivery (see Cooldown and Suppression below). For example, "alert me when bot crashes reach 3 occurrences within 15 minutes."

Threshold Alerts

Threshold alerts fire when a resource metric crosses a configured boundary. They support both >= (greater than or equal) and <= (less than or equal) operators.

Delivery Channels

Each alert rule can use one or both delivery channels:

Email

Configure up to 10 email recipients per rule. When an alert fires, all recipients receive an email containing:

• Alert rule name
• Current metric value and threshold
• Number of suppressed alerts during the cooldown period (if any)
• Direct link to the dashboard

Callback

Configure an HTTP endpoint to receive alert notifications programmatically. Callbacks are sent as POST requests with a JSON payload:

{
  "alert_rule_id": "550e8400-e29b-41d4-a716-446655440000",
  "alert_rule_name": "Bot Crash Monitor",
  "alert_type": "bot_crash",
  "category": "operational",
  "triggered_at": "2025-01-15T10:30:00.000Z",
  "current_value": 3,
  "threshold_value": 3,
  "suppressed_count": 0,
  "message": "Bot Crash: 3 occurrence(s) reached threshold of 3"
}

If you configure a secret on the callback, it is included as the x-mb-alert-secret header for verification.

Callback retry behavior:

• 4 total attempts (initial + 3 retries)
• Retry delays: 1 second, 5 seconds, 15 seconds
• Only retries on network errors and 5xx server responses
• Does not retry on 4xx client errors
• 30-second request timeout

Cooldown and Suppression

The cooldown period (default: 15 minutes) serves a dual purpose — it is both the counting window for accumulating events toward a threshold and the suppression window that prevents repeated alerts after delivery.

How it works:

1. Events are counted within a rolling window equal to the cooldown period
2. When the count reaches the threshold, the alert fires and delivery begins
3. After delivery, the cooldown starts — additional events during this period are counted but not delivered
4. When the cooldown expires and the next trigger occurs, the alert fires again with a suppressed_count showing how many events were batched during the suppression period

Example: You configure a "Bot Join Failed" alert with threshold >= 1 and a 15-minute cooldown.

• 10:00 — First bot join fails → threshold met, alert fires immediately
• 10:02 — Second failure → suppressed (cooldown active)
• 10:08 — Third failure → suppressed (cooldown active)
• 10:16 — Fourth failure → cooldown expired, alert fires with suppressed_count: 2

Testing Alerts

Use the Test button on any alert rule to send a test notification to all configured delivery channels. This verifies that your email addresses are correct and your callback endpoint is reachable.

Alert History

Each alert rule maintains a delivery history accessible from the rule's detail page. History entries include:

• When the alert fired
• Current value at the time of trigger
• Number of suppressed events
• Delivery status for each channel (success or failure with error details)

Limits