Monitoring & Alerts
Alert rules, notification channels, issue tracking, and auto-resolve behavior.
Hookstream turns delivery problems into actionable signal through three connected pieces: issues (auto-detected problems), alert rules (configurable triggers over metrics), and notification channels (where alerts go). A cron runs every 5 minutes evaluating every rule and sending notifications.
Issues: auto-detected problems
Issues are created automatically when something breaks:
- A delivery fails after all retries are exhausted.
- A destination's circuit breaker opens.
- Error rate crosses an internal threshold.
Each issue tracks severity, affected source/destination, failure count, and a timeline of related attempts. Issues auto-resolve after 30 minutes of no new matching failures — or you can manually resolve them with PATCH /v1/issues/:id.
Alert rule types
Hookstream supports five alert types. Each takes a rule_config with thresholds specific to the type.
| Type | Triggers when | rule_config |
|---|---|---|
failure_rate | Delivery failure rate exceeds a percentage over the evaluation window. | { "threshold": 10 } |
latency | p95 delivery latency exceeds a millisecond threshold. | { "threshold": 2000 } |
volume_drop | Event volume drops below a threshold vs the previous window. | { "threshold": 50 } |
dlq | DLQ event count exceeds a number. | { "threshold": 5 } |
issue_opened | A new issue is created. | {} |
Create an alert rule
Create a notification channel
Hookstream supports two channel types: webhook (HTTP POST to a URL, optionally HMAC-signed) and email (delivered via Resend).
curl -X POST https://hookstream.io/v1/notification-channels \
-H "X-API-Key: $HOOKSTREAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ops Webhook",
"channel_type": "webhook",
"config": {
"url": "https://ops.example.com/alerts",
"secret": "optional_hmac_secret"
}
}'curl -X POST https://hookstream.io/v1/notification-channels \
-H "X-API-Key: $HOOKSTREAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Team Email",
"channel_type": "email",
"config": { "to": "oncall@example.com" }
}'Webhook notifications include an X-hookstream-Signature header (HMAC-SHA256) when secret is set. Test any channel with POST /v1/notification-channels/:id/test.
Create an alert rule
Link one or more channels to the rule and set a cooldown so you don't get paged 50 times in a row:
bashcurl -X POST https://hookstream.io/v1/alert-rules \ -H "X-API-Key: $HOOKSTREAM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "High Failure Rate", "rule_type": "failure_rate", "rule_config": { "threshold": 10 }, "channel_ids": ["ch_abc"], "cooldown_minutes": 60 }'
Wait (up to 5 minutes) or force an eval
The cron runs every 5 minutes. For testing, tripping the rule intentionally (post some failing deliveries) and waiting a cycle is the fastest way to confirm it works end to end.
Auto-resolve
Open issues and fired alerts auto-resolve after 30 minutes without a matching event. The same 5-minute cron that evaluates rules also closes stable issues. If you need immediate resolution, PATCH /v1/issues/:id with status: "resolved".
Troubleshooting
Rules are gated by cooldown_minutes — if it fired recently, it won't fire again until the cooldown expires. Also check rule_config.threshold is lower than current actual values, and that the rule is enabled.
If you set config.secret, you need to verify the X-hookstream-Signature header on your side. See Outbound Signing for a receiver verification snippet — the algorithm is the same.
Each rule dedupes via its cooldown, but multiple rules can fire on the same underlying event (e.g. both failure_rate and issue_opened). That's intentional — if you want one-signal-per-incident, pick a single rule and disable the rest.