> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Event Monitoring & Alerting — Integration

> Feature ID: PF-48 Status: ✅ Complete Spec: PF-48-security-event-monitoring.md Last Updated: 2026-02-12

**Feature ID:** PF-48\
**Status:** ✅ Complete\
**Spec:** [PF-48-security-event-monitoring.md](../../../specs/pf/specs/PF-48-security-event-monitoring.md)\
**Last Updated:** 2026-02-12

***

## Overview

PF-48 integrates with PF-04 (Audit Logging), PF-10 (Notifications), and PF-36 (System Health Dashboard) via event-based and platform patterns. Security events are emitted from the database (trigger → pg\_notify / Database Webhook) and consumed by an Edge Function that delivers alerts and feeds dashboards.

***

## Integration Points (from Spec)

| Dependency                      | Pattern          | Purpose                                                                          |
| ------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| PF-04 (Audit Logging)           | Event / Audit    | All security events are audited                                                  |
| PF-10 (Notifications)           | Event / Platform | Security alerts sent via notification system (email, in-app; SMS when supported) |
| PF-36 (System Health Dashboard) | Event / Data     | Security events displayed on health dashboard                                    |

***

## Event Contract

**Event name:** `security_event_detected` (logical). **Table:** `pf_security_events`. Channel/payload: `security_event` pg\_notify or Database Webhook payload.

* **Publisher:** PF-48 (security event monitoring; INSERT on `pf_security_events`)
* **Subscribers:** PF-04 (Audit), PF-10 (Notifications), PF-36 (Health Dashboard)
* **Payload (notification payload shape):**
  * `event_id`: uuid
  * `organization_id`: uuid (nullable for pre-auth/system events)
  * `event_type`: text
  * `severity`: text
* **Handler requirements:** Handlers MUST (1) refetch the full row from `pf_security_events` by `event_id` before any sensitive processing; (2) verify `fetched_row.organization_id` matches `notification.organization_id` and enforce org-level authorization; (3) validate payload keys (`event_id`, `organization_id`, `event_type`, `severity`) before processing; (4) implement resilient delivery (retries with backoff, DLQ for permanent failures) to prevent TOCTOU and ensure authorization checks. See spec Downstream Service Contract.
* **Documentation:** [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) — add PF-48 entry when implemented.

***

## Implementation Notes

* **Downstream handler:** Supabase Database Webhook on `pf_security_events` INSERT invokes an Edge Function. The function refetches the event row from `pf_security_events`, enforces org-level authorization, then calls PF-10 for delivery and may log to PF-04 / feed PF-36.
* **Dead-letter:** On permanent delivery failure, the handler MUST write a row to `pf_security_alert_delivery_failures` (see spec Data Model). No PHI in payload\_reference.
* **IP blocking:** Enforced at edge/API layer (document exact point in implementation plan).

***

## Related Docs

* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)