Alert Rules

Define threshold-based alerts for error rates, latency, volume, DLQ, and circuit breakers.

Alert rules define conditions that trigger notifications. hookstream evaluates alert rules every 5 minutes via a Cron trigger. When a rule's threshold is exceeded, notifications are sent to configured channels. Rules auto-resolve after 30 minutes if the condition clears.

Five alert types are supported: failure_rate, latency, volume_drop, dlq, and issue_opened.

List Alert Rules

GET /v1/alert-rules

List all alert rules.

Authentication: API key or session cookie.

json
{
  "alert_rules": [
    {
      "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
      "name": "High Error Rate",
      "rule_type": "failure_rate",
      "rule_config": { "threshold": 0.1 },
      "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
      "cooldown_minutes": 60,
      "enabled": true,
      "last_triggered_at": null,
      "created_at": "2026-02-28T10:00:00Z"
    }
  ]
}

Create Alert Rule

POST /v1/alert-rules

Create a new alert rule.

Authentication: API key or session cookie.

Body Parameters

name string required

Display name for the rule.

rule_type string required

Alert type: failure_rate, latency, volume_drop, dlq, or issue_opened.

rule_config object

Type-specific configuration:

  • failure_rate: { threshold } (decimal, e.g., 0.1 for 10%)
  • latency: { threshold_ms, percentile_target }
  • volume_drop: { threshold }
  • dlq: { threshold }
channel_ids string[]

Array of notification channel IDs to send alerts to.

cooldown_minutes number default: 60

Minimum minutes between alert triggers.

bash
curl -X POST https://hookstream.io/v1/alert-rules \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.1 },
    "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
    "cooldown_minutes": 60
  }'

json
{
  "alert_rule": {
    "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.1 },
    "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
    "cooldown_minutes": 60,
    "enabled": true,
    "created_at": "2026-03-01T12:00:00Z"
  }
}

Retrieve Alert Rule

GET /v1/alert-rules/:id

Get a single alert rule with its trigger history.

Authentication: API key or session cookie.

json
{
  "alert_rule": {
    "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.1 },
    "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
    "cooldown_minutes": 60,
    "enabled": true,
    "last_triggered_at": "2026-03-01T10:05:00Z",
    "created_at": "2026-02-28T10:00:00Z"
  },
  "history": [
    {
      "id": "ah_1a2b3c",
      "alert_rule_id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
      "triggered_at": "2026-03-01T10:05:00Z",
      "message": "Failure rate 15% exceeds 10% threshold",
      "created_at": "2026-03-01T10:05:00Z"
    }
  ]
}

Update Alert Rule

PATCH /v1/alert-rules/:id

Update an alert rule.

Authentication: API key or session cookie.

bash
curl -X PATCH https://hookstream.io/v1/alert-rules/ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rule_config": {"threshold": 0.05}, "cooldown_minutes": 30}'

json
{
  "alert_rule": {
    "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.05 },
    "cooldown_minutes": 30,
    "updated_at": "2026-03-01T15:00:00Z"
  }
}

Delete Alert Rule

DELETE /v1/alert-rules/:id

Delete an alert rule.

Authentication: API key or session cookie.

json
{ "deleted": true }
Previous Notification Channels
Next Collections
Ask a question... ⌘I