Skip to main content
Alerting allows you to monitor your voice AI operations by creating rules that trigger notifications when specific metrics cross defined thresholds. Instead of manually checking dashboards, you receive automatic email or webhook notifications when issues arise.
Alert rules list

​
Use Cases

  • Monitor call volume: Get notified when call volume spikes or drops unexpectedly
  • Track system health: Alert when API errors or function failures increase
  • Monitor costs: Set budget alerts when call costs exceed thresholds
  • Detect quality issues: Alert on declining call success rates or negative sentiment

​
Available Metrics

You can create alerts for the following metrics:
MetricDescription
Call CountTotal number of calls within the evaluation window
Concurrency UsedPeak number of concurrent calls
Call Success RatePercentage of successful calls (0-100%)
Negative Sentiment RatePercentage of calls with negative sentiment (0-100%)
Custom Function LatencyAverage latency of custom function calls (milliseconds)
Custom Function Failure CountNumber of failed custom function calls
Transfer Call Failure CountNumber of failed call transfers
Total Call CostTotal cost of calls (USD)
API Error CountNumber of API errors (can be filtered by error code)

​
Creating an Alert Rule

Navigate to the Alerting tab in your dashboard to create alert rules.
Create alert rule
Each alert rule requires:
  1. Name: A descriptive name for the alert
  2. Metric: The metric to monitor
  3. Threshold type: Absolute or relative comparison
  4. Threshold value: The value to compare against
  5. Comparator: Greater than, less than, etc.
  6. Evaluation window: Time period for metric aggregation
  7. Frequency: How often to evaluate the rule
  8. Notification channels: Email addresses and/or webhook URLs

​
Threshold Types

​
Absolute Threshold

Compares the current metric value directly against your threshold. Example: Alert when Call Count > 100 in the last hour.

​
Relative Threshold

Compares the percentage change from the previous period against your threshold. Useful for detecting sudden spikes or drops. Example: Alert when Call Count increases by more than 50% compared to the previous hour. The formula used: ((currentValue - previousValue) / previousValue) * 100
If the previous period had zero calls but the current period has calls, this is treated as an infinite increase and will trigger alerts with > or >= comparators.

​
Evaluation Windows and Frequencies

The evaluation window determines how far back to look when calculating the metric. The frequency determines how often the rule is checked.
WindowSupported Frequencies
1 minute1 minute
5 minutes1 minute, 5 minutes
30 minutes5 minutes, 30 minutes
1 hour5 minutes, 30 minutes, 1 hour
12 hours30 minutes, 1 hour, 12 hours
24 hours1 hour, 12 hours, 24 hours
3 days12 hours, 24 hours
7 days24 hours
Choose a frequency that balances responsiveness with noise. A 1-minute frequency catches issues quickly but may trigger on brief spikes.

​
Filters

You can optionally filter the data included in metric calculations:

​
Agent Filter

Filter by specific agents and optionally by agent versions.

​
Disconnection Reason Filter

Filter calls by their disconnection reason (e.g., user_hangup, agent_hangup).

​
Error Code Filter

For the API Error Count metric, filter by specific HTTP status codes (e.g., 429, 402).

​
Notification Channels

​
Email Notifications

Add email addresses to receive alert notifications. When an alert triggers, all configured recipients receive an email containing:
  • Alert rule name
  • Metric type
  • Current value
  • Threshold that was breached
  • Timestamp

​
Webhook Notifications

Configure webhook URLs to receive programmatic notifications. This enables integration with external monitoring systems, Slack, PagerDuty, or custom workflows.

​
Webhook Payload

Webhooks send a POST request with the following payload structure: 
{
  "event": "alert_triggered",
  "alert": {
    "alert_incident_id": "abc123def456...",
    "alert_rule_id": "alert_rule_xyz789...",
    "name": "High Call Volume Alert",
    "metric_type": "call_count",
    "threshold_type": "absolute",
    "threshold_value": 100,
    "comparator": ">",
    "frequency": "1h",
    "window": "1h",
    "current_value": 150,
    "triggered_timestamp": 1714608475945
  }
}

​
Webhook Signature Verification

All webhook requests include an X-Retell-Signature header containing an HMAC-SHA256 signature. Use your organization’s webhook key to verify the payload authenticity. 
import Retell from 'retell-sdk';

// Verify the webhook signature
const isValid = Retell.verify(
  JSON.stringify(payload),
  apiKey,
  signature // from X-Retell-Signature header
);
Always verify webhook signatures in production to ensure requests originate from Retell.

​
Alert Incidents

When an alert rule’s condition is met, an alert incident is created. Incidents track:
  • When the alert was triggered
  • The metric value that triggered it
  • When the alert was resolved (if applicable)
Alert incidents list

​
Incident Lifecycle

  1. Triggered: When the metric breaches the threshold, a new incident is created and notifications are sent
  2. Active: The incident remains active while the condition persists
  3. Resolved: When the metric no longer breaches the threshold, the incident is marked as resolved
Only one incident can be active per alert rule at a time. Notifications are sent only when a new incident is created, not on each evaluation.

​
Limits

  • Maximum 10 alert rules per organization
  • Webhook timeout: 10 seconds

​
FAQ

Alerts are evaluated based on their configured frequency (1 minute to 24 hours). The system checks all due alert rules every minute and processes them according to their individual schedules.
No. Notifications are sent only once when a new incident is created. You won’t receive repeated notifications while the alert condition persists. A new notification is sent only if the alert resolves and then triggers again.
When the metric no longer meets the threshold condition, the active incident is marked as resolved with a timestamp. Currently, resolution notifications are not sent automatically.
Yes. You can select multiple agents in the filter configuration. The metric will be calculated across all selected agents.
If the previous period had zero activity but the current period has activity, this is treated as an infinite increase. Alerts with > or >= comparators will trigger in this case.