Smart Alerts

Field	Value
Document ID	ASCEND-NOTIF-003
Version	1.0.0
Last Updated	December 19, 2025
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 8 minutes | Skill Level: Intermediate

Overview

Smart Alerts provide real-time monitoring and alerting based on customizable rules. Alert on risk score thresholds, action patterns, system health, and anomalies with automatic escalation.

Alert Engine Architecture

+---------------------------------------------------------------------+
|                    SMART ALERT ENGINE                                |
+---------------------------------------------------------------------+
|                                                                      |
|  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐              |
|  │   Metrics   │    │    Rules    │    │  Channels   │              |
|  │   Stream    │───▶│   Engine    │───▶│  Dispatch   │              |
|  └─────────────┘    └─────────────┘    └─────────────┘              |
|        │                  │                  │                       |
|        │            ┌─────┴─────┐            │                       |
|        │            │           │            │                       |
|        ▼            ▼           ▼            ▼                       |
|  ┌──────────┐  ┌──────────┐ ┌──────────┐ ┌──────────┐              |
|  │ System   │  │Threshold │ │ Anomaly  │ │ Webhook  │              |
|  │ Metrics  │  │  Check   │ │Detection │ │ Slack    │              |
|  │ Actions  │  │  Pattern │ │          │ │ Teams    │              |
|  └──────────┘  └──────────┘ └──────────┘ └──────────┘              |
|                                                                      |
+---------------------------------------------------------------------+

Creating Alert Rules

Threshold-Based Alerts

curl -X POST "https://pilot.owkai.app/api/smart-rules" \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Action Alert",
    "is_active": true,
    "rule_definition": {
      "condition_type": "threshold",
      "metric": "risk_score",
      "operator": ">=",
      "threshold": 80,
      "severity": "high"
    }
  }'

Pattern-Based Alerts

curl -X POST "https://pilot.owkai.app/api/smart-rules" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "name": "Repeated Denials Alert",
    "is_active": true,
    "rule_definition": {
      "condition_type": "pattern",
      "pattern": {
        "event": "action.denied",
        "count": 5,
        "window_minutes": 10
      },
      "severity": "critical"
    }
  }'

System Health Alerts

curl -X POST "https://pilot.owkai.app/api/smart-rules" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "name": "System CPU Alert",
    "is_active": true,
    "rule_definition": {
      "condition_type": "threshold",
      "metric": "system.cpu_percent",
      "operator": ">",
      "threshold": 90,
      "severity": "high"
    }
  }'

Severity Levels

Severity	Color	Use Case	Default Response
`critical`	Red	Security incidents, system down	Immediate escalation
`high`	Orange	High-risk actions, failures	5 minute response
`medium`	Yellow	Unusual patterns	15 minute response
`low`	Blue	Informational	Log only

Alert Lifecycle

1. Alert Triggered

When a rule condition is met:

{
  "id": "alert_42_1702656000",
  "rule_id": 42,
  "rule_name": "High Risk Action Alert",
  "severity": "high",
  "message": "High Risk Action Alert: risk_score is 85 (threshold: >= 80)",
  "triggered_at": "2025-12-15T10:00:00Z",
  "status": "active",
  "metrics_snapshot": {
    "risk_score": 85,
    "action_type": "data_export",
    "agent_id": "export-agent"
  }
}

2. Get Active Alerts

curl "https://pilot.owkai.app/api/alerts/active" \
  -H "Authorization: Bearer <jwt_token>"

Response:

{
  "alerts": [
    {
      "id": "alert_42_1702656000",
      "rule_name": "High Risk Action Alert",
      "severity": "high",
      "message": "risk_score is 85 (threshold: >= 80)",
      "triggered_at": "2025-12-15T10:00:00Z",
      "status": "active"
    }
  ],
  "statistics": {
    "total_active": 3,
    "by_severity": {
      "critical": 0,
      "high": 1,
      "medium": 2,
      "low": 0
    }
  }
}

3. Acknowledge Alert

curl -X POST "https://pilot.owkai.app/api/alerts/42/acknowledge" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "X-CSRF-Token: <csrf_token>"

4. Resolve Alert

curl -X POST "https://pilot.owkai.app/api/alerts/alert_42_1702656000/resolve" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "X-CSRF-Token: <csrf_token>"

5. Escalate Alert

curl -X POST "https://pilot.owkai.app/api/alerts/42/escalate" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "X-CSRF-Token: <csrf_token>"

Real-Time Alert Stream

WebSocket Connection

const ws = new WebSocket('wss://pilot.owkai.app/api/alerts/stream');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'initial_alerts') {
    console.log('Current active alerts:', data.data);
  } else if (data.type === 'alerts') {
    console.log('New alerts:', data.data);
    data.data.forEach(alert => {
      showNotification(alert);
    });
  }
};

Python WebSocket Client

import asyncio
import websockets
import json

async def alert_listener():
    uri = "wss://pilot.owkai.app/api/alerts/stream"
    headers = {"Authorization": "Bearer <jwt_token>"}

    async with websockets.connect(uri, extra_headers=headers) as ws:
        async for message in ws:
            data = json.loads(message)

            if data['type'] == 'alerts':
                for alert in data['data']:
                    handle_alert(alert)

def handle_alert(alert):
    if alert['severity'] == 'critical':
        send_pager_notification(alert)
    elif alert['severity'] == 'high':
        send_slack_notification(alert)

asyncio.run(alert_listener())

Alert History

Query Historical Alerts

curl "https://pilot.owkai.app/api/alerts/history?days=30" \
  -H "Authorization: Bearer <jwt_token>"

Response:

{
  "history": [
    {
      "id": "123",
      "rule_name": "High Risk Alert",
      "severity": "high",
      "triggered_at": "2025-12-14T15:30:00Z",
      "resolved_at": "2025-12-14T16:00:00Z",
      "status": "resolved"
    }
  ],
  "total_count": 45,
  "date_range": {
    "start": "2025-11-15T00:00:00Z",
    "end": "2025-12-15T23:59:59Z"
  }
}

Condition Types

Threshold Conditions

{
  "condition_type": "threshold",
  "metric": "risk_score",
  "operator": ">=",
  "threshold": 80
}

Supported Operators:

> - Greater than
< - Less than
>= - Greater than or equal
<= - Less than or equal
== - Equal to

Anomaly Detection

{
  "condition_type": "anomaly",
  "metric": "actions_per_minute",
  "sensitivity": 0.8,
  "historical_average": 50
}

Pattern Matching

{
  "condition_type": "pattern",
  "pattern": {
    "sequence": ["login_failed", "login_failed", "login_failed"],
    "window_minutes": 5
  }
}

Available Metrics

System Metrics

Metric	Description
`system.cpu_percent`	CPU utilization
`system.memory_percent`	Memory utilization
`system.disk_percent`	Disk utilization

Action Metrics

Metric	Description
`risk_score`	Action risk score (0-100)
`actions_per_minute`	Action submission rate
`denial_rate`	Percentage of denied actions

Agent Metrics

Metric	Description
`agent.error_rate`	Agent error percentage
`agent.response_time`	Average response time
`agent.active_count`	Active agent count

Integration with Notification Channels

Configure Alert Routing

curl -X POST "https://pilot.owkai.app/api/notifications/channels" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "name": "Critical Alerts - PagerDuty",
    "channel_type": "slack",
    "webhook_url": "https://hooks.slack.com/...",
    "subscribed_events": [
      "alert.critical",
      "alert.high"
    ],
    "min_risk_score": 80
  }'

Alert Notification Flow

Alert Triggered
      │
      ▼
┌─────────────────┐
│ Check Severity  │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
Critical   High/Medium
    │         │
    ▼         ▼
PagerDuty   Slack
    │         │
    ▼         ▼
On-Call    Channel

Best Practices

1. Set Meaningful Thresholds

{
  "name": "Actionable High Risk Alert",
  "rule_definition": {
    "condition_type": "threshold",
    "metric": "risk_score",
    "operator": ">=",
    "threshold": 85,
    "cooldown_minutes": 5
  }
}

2. Use Severity Appropriately

Critical: Security incidents only
High: Requires immediate attention
Medium: Review within the hour
Low: Informational

3. Configure Cooldowns

Prevent alert fatigue with cooldown periods:

{
  "rule_definition": {
    "cooldown_minutes": 15,
    "max_alerts_per_hour": 10
  }
}

4. Test Alerts

# Trigger a test alert
curl -X POST "https://pilot.owkai.app/api/alerts/test" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "rule_id": 42,
    "test_metrics": {"risk_score": 90}
  }'

Next Steps

Webhooks - External notifications
Slack/Teams - Chat integrations
PagerDuty - On-call alerting

Document Version: 1.0.0 | Last Updated: December 2025

Overview​

Alert Engine Architecture​

Creating Alert Rules​

Threshold-Based Alerts​

Pattern-Based Alerts​

System Health Alerts​

Severity Levels​

Alert Lifecycle​

1. Alert Triggered​

2. Get Active Alerts​

3. Acknowledge Alert​

4. Resolve Alert​

5. Escalate Alert​

Real-Time Alert Stream​

WebSocket Connection​

Python WebSocket Client​

Alert History​

Query Historical Alerts​

Condition Types​

Threshold Conditions​

Anomaly Detection​

Pattern Matching​

Available Metrics​

System Metrics​

Action Metrics​

Agent Metrics​

Integration with Notification Channels​

Configure Alert Routing​

Alert Notification Flow​

Best Practices​

1. Set Meaningful Thresholds​

2. Use Severity Appropriately​

3. Configure Cooldowns​

4. Test Alerts​

Next Steps​