<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Security Notification Systems — API Reference

## PagerDuty Events API v2

```python
import requests

# Trigger event
requests.post("https://events.pagerduty.com/v2/enqueue", json={
    "routing_key": "R0XXXXXXXXXXXX",
    "event_action": "trigger",
    "dedup_key": "soc-alert-12345",
    "payload": {
        "summary": "Critical: Ransomware detected on db-01",
        "severity": "critical",
        "source": "soar-engine",
        "component": "endpoint-protection",
        "group": "production",
        "custom_details": {"hostname": "db-01", "cve": "N/A"},
    },
})

# Acknowledge event
requests.post("https://events.pagerduty.com/v2/enqueue", json={
    "routing_key": "R0XXXXXXXXXXXX",
    "event_action": "acknowledge",
    "dedup_key": "soc-alert-12345",
})

# Resolve event
requests.post("https://events.pagerduty.com/v2/enqueue", json={
    "routing_key": "R0XXXXXXXXXXXX",
    "event_action": "resolve",
    "dedup_key": "soc-alert-12345",
})
```

## Slack Incoming Webhook

```python
requests.post("https://hooks.slack.com/services/T0XXXXXX/B0XXXXXX/XXXXXXXX", json={
    "text": "🔴 Critical: Ransomware detected on db-01",
    "channel": "#soc-alerts",
    "username": "Security Bot",
    "icon_emoji": ":rotating_light:",
})
```

## SMTP Email (Python)

```python
import smtplib
from email.mime.text import MIMEText

msg = MIMEText("Critical security alert: Ransomware detected on db-01")
msg["Subject"] = "[CRITICAL] Security Alert"
msg["From"] = "soc-alerts@corp.com"
msg["To"] = "soc-team@corp.com"

with smtplib.SMTP("smtp.corp.com", 587) as server:
    server.starttls()
    server.login("soc-alerts@corp.com", "password")
    server.send_message(msg)
```

## Escalation Timeout Matrix

| Severity | Tier 1 Timeout | Tier 2 Timeout | Manager Timeout |
|----------|---------------|---------------|-----------------|
| Critical | 5 min | 10 min | 15 min |
| High | 15 min | 30 min | 60 min |
| Medium | 60 min | N/A | N/A |
| Low | N/A | N/A | N/A |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Notification delivered |
| 1 | Partial delivery — some channels failed |
| 2 | Delivery failed |
