Subscriber Alerts

Monitor notification subscriber health with threshold-based alerts on delivery metrics.

Subscriber Alerts monitor the health of your notification subscribers. They track delivery metrics — failure rate, failure count, success rate, and total volume — and fire when a threshold is breached.

Overview

Every time a notification is processed, the result (success or error) is logged in the audits table. Subscriber alerts query these audit records over a configurable time window and compare the result against a threshold.

When a subscriber alert fires, it creates a provenance interaction — which means it can trigger downstream notification subscriptions just like any other interaction.

How it works

Notification processed → Audit record created (success/error)
                                    ↓
            POST /api/alerts/process (cron or manual)
                                    ↓
            For each active alert:
              1. Query audits for subscriber within time window
              2. Calculate metric (failure_rate, success_rate, etc.)
              3. Compare against threshold
              4. If exceeded → create interaction

Creating a subscriber alert

POST /api/alerts
{
  "subscriberId": "uuid",
  "name": "High Failure Rate — SendGrid",
  "metric_type": "failure_rate",
  "condition": ">",
  "threshold": 10,
  "time_window": "1h",
  "severity": "critical",
  "resourceTypeId": "uuid",
  "actionId": "uuid"
}

Fields

Field	Required	Description
`subscriberId`	Yes	The subscriber to monitor
`name`	Yes	Human-readable alert name
`metric_type`	Yes	What to measure (see below)
`condition`	Yes	Comparison operator
`threshold`	Yes	Numeric threshold value
`time_window`	Yes	Lookback window for metric calculation
`severity`	Yes	Alert severity level
`resourceTypeId`	No	Resource type for the alert interaction (defaults to system `ALERT` type)
`actionId`	No	Action for the alert interaction (defaults to system `ALERTTRIG` action)

Metric types

Metric	Description	Unit
`failure_rate`	Percentage of failed notifications	`%` (0–100)
`failure_count`	Absolute number of failures	count
`success_rate`	Percentage of successful notifications	`%` (0–100)
`total_count`	Total notifications processed	count

Conditions

Operator	Meaning
`>`	Greater than
`<`	Less than
`>=`	Greater than or equal
`<=`	Less than or equal
`==`	Equal to

Time window format

Format	Example	Meaning
`{n}m`	`5m`	5 minutes
`{n}h`	`1h`	1 hour
`{n}d`	`7d`	7 days

Severity levels

info — informational, no action needed
warning — something to watch
critical — immediate attention required

Alert interaction data

When a subscriber alert fires, it creates an interaction with this structure in the interaction JSON field:

{
  "alert": {
    "subscriberAlertId": "uuid",
    "name": "High Failure Rate — SendGrid",
    "severity": "critical",
    "metric_type": "failure_rate",
    "condition": ">",
    "threshold": 10,
    "time_window": "1h",
    "triggered_at": "2026-03-20T14:30:00.000Z"
  },
  "subscriber": {
    "subscriberId": "uuid",
    "subscriberName": "SendGrid",
    "subscriberArn": "adapter:email"
  },
  "metrics": {
    "current_value": 15.5,
    "total_count": 200,
    "success_count": 169,
    "failure_count": 31,
    "success_rate": 84.5,
    "failure_rate": 15.5
  }
}

The interaction is created with:

Field	Value
`resourceId`	`alert-{subscriberId}-{metric_type}`
`resourceTypeId`	Alert's configured resource type, or system `ALERT` type
`actionId`	Alert's configured action, or system `ALERTTRIG` action
`originId`	System `ALERTING` origin
`externalReference`	`alert-{subscriberAlertId}`
`uowId`	Auto-generated UUID

System entities required

Subscriber alerts require these system entities to exist:

Entity	Mnemonic	Purpose
Resource Type	`ALERT`	Default resource type for alert interactions
Action	`ALERTTRIG`	Default action for alert interactions
Origin	`ALERTING`	Origin for all subscriber alert interactions

If these don't exist, alert processing will fail with Missing required default alert resource type, action, or origin.

Processing alerts

Alerts are evaluated on demand — either manually or via a cron job.

Manual evaluation

POST /api/alerts/process

Returns:

{
  "processed": 5,
  "results": [
    {
      "subscriberAlertId": "uuid",
      "triggered": true,
      "interactionId": "uuid",
      "currentValue": 15.5,
      "threshold": 10
    },
    {
      "subscriberAlertId": "uuid",
      "triggered": false,
      "currentValue": 2.1,
      "threshold": 10
    }
  ]
}

Cron job

# Evaluate every minute
* * * * * curl -X POST https://your-api.com/api/alerts/process \
  -H "x-api-key: your-key"

Check individual alert status

GET /api/alerts/:alertId/firing

Returns:

{
  "isFiring": true,
  "currentValue": 15.5,
  "threshold": 10,
  "condition": ">",
  "metric_type": "failure_rate"
}

API reference

Method	Endpoint	Description
`GET`	`/api/alerts`	List all subscriber alerts
`GET`	`/api/alerts/:id`	Get alert by ID
`POST`	`/api/alerts`	Create alert
`PUT`	`/api/alerts/:id`	Update alert
`DELETE`	`/api/alerts/:id`	Delete alert
`POST`	`/api/alerts/process`	Evaluate all active alerts
`GET`	`/api/alerts/:id/firing`	Check if alert is currently firing

Example: Alert on SendGrid failures

# 1. Create the alert
POST /api/alerts
{
  "subscriberId": "sendgrid-subscriber-uuid",
  "name": "SendGrid failure rate > 5%",
  "metric_type": "failure_rate",
  "condition": ">",
  "threshold": 5,
  "time_window": "1h",
  "severity": "warning"
}

# 2. Process alerts (or set up cron)
POST /api/alerts/process

# 3. Check status
GET /api/alerts/{alertId}/firing

On this page