guibranco / guibranco/logstream-server
[FEATURE] Threshold alerts via webhook
- Dominant language
- PHP
- Stars
- 1
- Forks
- 0
- Avg merge
- 1m
- Merged PRs (30d)
- 4
Description
## Summary
Trigger an outbound HTTP `POST` to a configured URL when a log condition is met, turning logstream-server from a passive store into an active monitoring tool.
## Motivation
Currently there is no way to know when something goes wrong without manually checking the UI or polling the API. Webhook alerts enable proactive incident response.
## Proposed triggers
- More than **N** `error` / `critical` entries from an `app_key` in the last **X** minutes
- A registered client goes silent for more than **Y** minutes (dead client / heartbeat detection)
- Any entry whose `message` matches a configured **PCRE regex**
## Proposed configuration
```json
{
"alerts": [
{
"name": "billing-errors",
"app_key": "billing-api",
"level": "error",
"threshold": 5,
"window_minutes": 5,
"webhook_url": "https://hooks.slack.com/..."
},
{
"name": "pii-pattern",
"message_regex": ".*@hotmail\\.com",
"threshold": 1,
"window_minutes": 1,
"webhook_url": "https://example.com/security-alert"
}
]
}
```
## Webhook payload
```json
{
"alert": "billing-errors",
"triggered": "2026-04-17T16:00:00+00:00",
"count": 7,
"window": "5m",
"app_key": "billing-api",
"sample": {}
}
```
## Implementation notes
- ReactPHP periodic timer (every 30 s) checks aggregate counts
- `ALERT_CONFIG=./alerts.json` env var to enable
- `POST /api/alerts/test/{name}` endpoint to fire a test webhook
- Alert cooldown to prevent repeated firing within the same window
## Acceptance criteria
- [ ] Alert config loaded from `alerts.json` at startup
- [ ] Threshold-based alerts fire correctly
- [ ] Dead client detection fires after configurable silence period
- [ ] Regex-based alerts fire on matching entries
- [ ] Webhook payload contains alert name, timestamp, count, and a sample entry
- [ ] Cooldown prevents repeated alerts within the same window
- [ ] `POST /api/alerts/test/{name}` fires a test payload
- [ ] Unit tests for alert evaluation logic
- [ ] Documentation in `docs/user-guide/alerts.md`
Contributor guide
Research direction
Start by locating the existing configuration and API entry points before designing the alert flow; the issue names ALERT_CONFIG=./alerts.json, a ReactPHP periodic timer, and POST /api/alerts/test/{name}. Done means all listed trigger types, cooldown behavior, webhook payload fields, unit tests, and docs/user-guide/alerts.md are implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, backend, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100