Setting Up Compliance Alerts¶

Proactive alerting is essential for effective compliance management. CalcBridge provides a comprehensive alerting system that notifies you immediately when compliance tests fail, approach thresholds, or show concerning trends.

Alert Types¶

CalcBridge supports three categories of compliance alerts:

Alert Type	Trigger	Use Case
Compliance	Test failure or warning	Immediate breach notification
Threshold	Cushion below configured level	Early warning before breach
Reconciliation	Data discrepancies detected	Data quality issues

Creating Alert Rules¶

Via API¶

Create a new alert configuration using the REST API:

curl -X POST https://api.calcbridge.io/api/v1/alerts/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config_name": "Critical Compliance Failures",
    "description": "Alert on critical compliance test failures",
    "alert_type": "compliance",
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "thresholds": {
      "test_categories": ["concentration", "rating", "coverage"],
      "trigger_on_fail": true,
      "trigger_on_warning": true,
      "critical_cushion_pct": 5.0
    },
    "channels": [
      {
        "type": "email",
        "enabled": true,
        "config": {
          "recipients": ["compliance@example.com", "pm@example.com"],
          "subject_prefix": "[CalcBridge ALERT]"
        }
      },
      {
        "type": "slack",
        "enabled": true,
        "config": {
          "webhook_url": "https://hooks.slack.com/services/T00/B00/XXX",
          "channel": "#compliance-alerts",
          "mention_users": ["U12345"]
        }
      }
    ],
    "enabled": true,
    "schedule": "0 */2 * * *"
  }'

Response:

{
  "id": "alert_cfg_abc123",
  "config_name": "Critical Compliance Failures",
  "description": "Alert on critical compliance test failures",
  "alert_type": "compliance",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "thresholds": {
    "test_categories": ["concentration", "rating", "coverage"],
    "trigger_on_fail": true,
    "trigger_on_warning": true,
    "critical_cushion_pct": 5.0
  },
  "channels": [...],
  "enabled": true,
  "schedule": "0 */2 * * *",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Via UI¶

Navigate to Settings > Alerts > Alert Configurations
Click Create New Alert
Configure the alert parameters:
Name and description
Alert type
Scope (all workbooks or specific)
Trigger conditions
Notification channels
Click Save

Alert configuration interface

Alert Channels¶

Email Notifications¶

Configure email alerts with customizable formatting:

{
  "type": "email",
  "enabled": true,
  "config": {
    "recipients": [
      "compliance@example.com",
      "pm@example.com"
    ],
    "cc": [
      "operations@example.com"
    ],
    "subject_prefix": "[CalcBridge]",
    "include_details": true,
    "include_recommendations": true,
    "priority": "high"
  }
}

Email Alert Example:

Subject: [CalcBridge ALERT] Compliance Failure - CLO 2024-1

COMPLIANCE ALERT

Deal: CLO 2024-1
Time: January 15, 2024 10:30 AM EST
Severity: HIGH

FAILED TESTS (1)

1. CCC Bucket
   Current Value: 8.12%
   Threshold: 7.50%
   Breach Amount: 0.62%

   Contributing Factors:
   - XYZ Holdings downgraded from B3 to Caa1 on Jan 14

WARNINGS (2)

1. WAL Test
   Current Value: 4.82 years
   Threshold: 5.00 years
   Cushion: 3.6%

2. Single Obligor - ACME Corp
   Current Value: 9.45%
   Threshold: 10.00%
   Cushion: 5.5%

RECOMMENDATIONS

- Review CCC bucket exposure and consider sell-down
- Monitor WAL trend - approaching threshold
- Prepare remediation plan for trustee

---
CalcBridge Compliance Monitoring
View full results: https://app.calcbridge.io/compliance/results/xxx

Webhook Integration¶

Send alerts to any HTTP endpoint:

{
  "type": "webhook",
  "enabled": true,
  "config": {
    "url": "https://your-app.com/webhooks/calcbridge",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your_webhook_secret",
      "Content-Type": "application/json"
    },
    "retry_count": 3,
    "retry_delay_seconds": 30
  }
}

Webhook Payload:

{
  "event_type": "compliance.alert",
  "timestamp": "2024-01-15T10:30:00Z",
  "alert_id": "alert_xyz789",
  "severity": "high",
  "workbook": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "CLO 2024-1"
  },
  "summary": {
    "total_tests": 24,
    "passed": 22,
    "warnings": 1,
    "failed": 1
  },
  "failed_tests": [
    {
      "test_name": "CCC Bucket",
      "test_category": "rating",
      "current_value": "8.12",
      "threshold_value": "7.50",
      "breach_amount": "0.62",
      "description": "CCC/Caa exposure: 8.12% (limit: 7.5%)"
    }
  ],
  "warning_tests": [...],
  "metadata": {
    "snapshot_date": "2024-01-15T10:00:00Z",
    "job_id": "job_abc123"
  }
}

Slack Integration¶

Send rich alerts to Slack channels:

{
  "type": "slack",
  "enabled": true,
  "config": {
    "webhook_url": "https://hooks.slack.com/services/T00/B00/XXX",
    "channel": "#compliance-alerts",
    "username": "CalcBridge Bot",
    "icon_emoji": ":warning:",
    "mention_users": ["U12345", "U67890"],
    "mention_on_fail": true,
    "mention_on_warning": false
  }
}

Slack Message Format:

:rotating_light: *Compliance Alert - CLO 2024-1*

*Status:* 1 Failed, 1 Warning
*Time:* Jan 15, 2024 10:30 AM EST

*Failed Tests:*
> :x: CCC Bucket: 8.12% (limit: 7.50%)

*Warnings:*
> :warning: WAL: 4.82 years (limit: 5.00 years)

@john.smith @jane.doe - Please review

<https://app.calcbridge.io/compliance/results/xxx|View Full Results>

PagerDuty Integration¶

Escalate critical alerts through PagerDuty:

{
  "type": "pagerduty",
  "enabled": true,
  "config": {
    "routing_key": "your_pagerduty_routing_key",
    "severity_mapping": {
      "critical": "critical",
      "high": "error",
      "medium": "warning",
      "low": "info"
    },
    "dedup_key_prefix": "calcbridge_compliance",
    "auto_resolve": true
  }
}

Alert Severity Levels¶

Configure alert severity to control escalation:

Severity	Trigger Condition	Default Channels
Critical	Multiple failures or breach > 2%	All channels + PagerDuty
Error	Single failure or breach 1-2%	Email + Slack
Warning	Warning status (approaching threshold)	Email
Info	Predictive alerts, trend changes	Dashboard only

Severity Configuration¶

{
  "severity_rules": {
    "critical": {
      "conditions": [
        {"type": "breach_count", "operator": ">=", "value": 2},
        {"type": "breach_amount_pct", "operator": ">=", "value": 2.0},
        {"type": "test_category", "value": "coverage"}
      ],
      "channels": ["email", "slack", "pagerduty"]
    },
    "error": {
      "conditions": [
        {"type": "breach_count", "operator": ">=", "value": 1},
        {"type": "breach_amount_pct", "operator": ">=", "value": 1.0}
      ],
      "channels": ["email", "slack"]
    },
    "warning": {
      "conditions": [
        {"type": "status", "value": "warning"},
        {"type": "cushion_pct", "operator": "<=", "value": 10.0}
      ],
      "channels": ["email"]
    }
  }
}

Managing Alert Fatigue¶

Alert fatigue occurs when too many alerts desensitize recipients to important notifications. CalcBridge provides several features to manage alert volume.

Alert Deduplication¶

Prevent duplicate alerts for the same issue:

{
  "deduplication": {
    "enabled": true,
    "window_minutes": 60,
    "key_fields": ["workbook_id", "test_name", "status"]
  }
}

Alert Aggregation¶

Combine multiple alerts into a single notification:

{
  "aggregation": {
    "enabled": true,
    "window_minutes": 15,
    "max_alerts_per_notification": 10,
    "group_by": ["workbook_id"]
  }
}

Quiet Hours¶

Suppress non-critical alerts during off-hours:

{
  "quiet_hours": {
    "enabled": true,
    "timezone": "America/New_York",
    "start": "20:00",
    "end": "06:00",
    "suppress_severity": ["warning", "info"],
    "weekend_mode": "suppress_all_except_critical"
  }
}

Alert Routing by Time¶

Route alerts differently based on time of day:

{
  "time_based_routing": {
    "business_hours": {
      "start": "08:00",
      "end": "18:00",
      "timezone": "America/New_York",
      "channels": ["email", "slack"]
    },
    "after_hours": {
      "channels": ["pagerduty"],
      "severity_filter": ["critical", "error"]
    }
  }
}

Alert History and Acknowledgment¶

Viewing Alert History¶

curl -X GET "https://api.calcbridge.io/api/v1/alerts/history" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "page": 1,
    "page_size": 50,
    "alert_type": "compliance",
    "severity": "error",
    "acknowledged": false,
    "start_date": "2024-01-01",
    "end_date": "2024-01-15"
  }'

Response:

{
  "items": [
    {
      "id": "alert_hist_001",
      "config_id": "alert_cfg_abc123",
      "alert_type": "compliance",
      "severity": "error",
      "message": "Compliance failure: CCC Bucket at 8.12% (limit: 7.50%)",
      "context": {
        "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
        "test_name": "CCC Bucket",
        "current_value": "8.12",
        "threshold": "7.50"
      },
      "delivered_channels": ["email", "slack"],
      "triggered_at": "2024-01-15T10:30:00Z",
      "acknowledged_at": null,
      "acknowledged_by": null
    }
  ],
  "total": 15,
  "page": 1,
  "page_size": 50,
  "pages": 1
}

Acknowledging Alerts¶

Mark alerts as acknowledged to track response:

curl -X POST "https://api.calcbridge.io/api/v1/alerts/history/{alert_id}/acknowledge" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "alert_hist_001",
  "acknowledged_at": "2024-01-15T10:45:00Z",
  "acknowledged_by": "user@example.com",
  "message": "Alert acknowledged successfully"
}

Unacknowledged Alert Counts¶

Get counts of pending alerts by severity:

curl -X GET "https://api.calcbridge.io/api/v1/alerts/unacknowledged/count" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "critical": 0,
  "error": 2,
  "warning": 5,
  "info": 12,
  "total": 19
}

Best Practices¶

Alert Configuration Best Practices

Start conservative, then tune - Begin with stricter thresholds and relax based on experience
Use severity appropriately - Reserve critical for true emergencies
Layer your alerts - Early warnings at 80%, alerts at 90%, critical at breach
Route by expertise - Send concentration alerts to PMs, coverage alerts to operations
Review alert effectiveness - Monthly review of alert-to-action ratio
Test your alerts - Use the test endpoint to verify configuration

Testing Alert Configuration¶

Send a test alert to verify your configuration:

curl -X POST "https://api.calcbridge.io/api/v1/alerts/config/{config_id}/test" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "test_data": {
      "severity": "warning",
      "test_name": "Test Alert",
      "current_value": "9.5",
      "threshold": "10.0"
    }
  }'

Integration Examples¶

Slack Bot with Interactive Actions¶

Configure alerts with actionable buttons:

{
  "type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/...",
    "interactive": true,
    "actions": [
      {
        "type": "button",
        "text": "View Details",
        "url_template": "https://app.calcbridge.io/compliance/{{job_id}}"
      },
      {
        "type": "button",
        "text": "Acknowledge",
        "action_id": "acknowledge_alert"
      },
      {
        "type": "button",
        "text": "Snooze 1hr",
        "action_id": "snooze_alert",
        "value": "60"
      }
    ]
  }
}

ServiceNow Integration¶

Create incidents automatically:

{
  "type": "webhook",
  "config": {
    "url": "https://your-instance.service-now.com/api/now/table/incident",
    "method": "POST",
    "headers": {
      "Authorization": "Basic xxx",
      "Content-Type": "application/json"
    },
    "body_template": {
      "short_description": "CalcBridge Compliance Alert: {{test_name}}",
      "description": "{{message}}",
      "urgency": "{{severity_to_servicenow_urgency}}",
      "category": "Compliance",
      "assignment_group": "CLO Operations"
    }
  }
}

Next: Generating Compliance Reports