Alert webhooks reference
Alert sources start investigations by posting to /webhooks/*. Each request is authenticated, parsed into one or more alerts, matched to catalog services, and either starts an investigation, is merged into one, resolves earlier ones, or is ignored.
Endpoints
| Method and path | Payload | Investigation source |
|---|---|---|
POST /webhooks/openstatus |
openstatus webhook notification | openstatus |
POST /webhooks/alertmanager |
Alertmanager webhook | alertmanager |
POST /webhooks/grafana |
Grafana alerting webhook (Alertmanager shape) | alertmanager |
POST /webhooks/generic |
generic JSON | webhook |
Bodies are read up to 1 MiB.
Authentication
The token is STROMBOLI_WEBHOOK_TOKEN, or STROMBOLI_API_TOKEN when it is unset. With neither set, webhooks are unauthenticated. The request’s token is taken from, in increasing priority:
- the
tokenquery parameter:?token=<token> Authorization: Bearer <token>(other schemes are ignored, so a proxy’s ownAuthorizationdoesn’t override?token=)X-Webhook-Secret: <token>
A wrong or missing token answers 401 unauthorized and logs webhook rejected: invalid or missing token with the path and user agent.
Payloads
openstatus
The openstatus webhook notification. Fields read:
| Field | Use |
|---|---|
monitor.id |
required. Service: the catalog entry whose monitors contains openstatus:<id>. Fingerprint: openstatus:<id> |
monitor.name, status, errorMessage |
title: openstatus monitor "<name>" is <status>[: <errorMessage>] |
cronTimestamp |
when the problem was observed (Unix milliseconds) |
status |
recovered resolves the alert |
The whole payload is kept as the investigation’s alert.
Alertmanager and Grafana
The Alertmanager webhook payload; each element of alerts is one alert.
| Field | Use |
|---|---|
labels.service, labels.service_name, labels.app, labels.job, labels.container |
service: the first of these that names a catalog service |
labels.alertname, annotations.summary |
title: <alertname>[: <summary>] |
fingerprint |
fingerprint alertmanager:<fingerprint>; without one, alertmanager:<alertname>/<labels.service> |
startsAt |
when the problem was observed |
status |
resolved resolves the alert |
The alert keeps labels, annotations, startsAt and generatorURL.
generic
{
"service": "api",
"title": "p95 latency above 2s",
"fingerprint": "api-latency",
"resolved": false,
"at": "2026-11-10T14:05:00Z",
"details": {"any": "json"}
}
| Field | |
|---|---|
service |
required. Catalog service name |
title |
required |
fingerprint |
dedupe key, stored as generic:<fingerprint>. Without it, every request starts a new investigation |
resolved |
true resolves the alert |
at |
RFC 3339 time the problem was observed; default now |
details |
free-form; kept in the alert as details |
Processing
For each alert, in order:
- Resolved (
recovered,resolved,"resolved": true): every unresolved investigation with the same fingerprint is marked resolved. No investigation starts. - No matching service: ignored, logged as
alert without a catalog service. - Duplicate: merged into an existing investigation (see below), logged as
alert deduplicated. - Otherwise a new investigation starts in the background.
Deduplication
An alert with a fingerprint is merged into the most recent investigation with the same fingerprint that:
- is not resolved, and
- is still running, or finished less than
STROMBOLI_DEDUPE_WINDOW(default30m) ago and has no machine action that succeeded.
So a repeat of an alert joins the running investigation; after it finishes, a repeat within the window reuses its result; once the alert resolved, or an approved action fixed something, the alert firing again is a new incident.
Investigation window
The brief and the agent look at the time from 30 minutes before the alert’s time (at, startsAt, cronTimestamp) until now, bounded to the last 24 hours. A time in the future is treated as now.
Response
202 Accepted with one result per alert:
{"alerts": [{"title": "…", "status": "started", "investigation_id": "7c9e6679-…"}]}
status |
investigation_id |
|---|---|
started |
the new investigation |
deduplicated |
the investigation it was merged into |
resolved |
none |
ignored: no matching service in the catalog |
none |
error: <message> |
none (e.g. no LLM configured) |
Errors before alerts are processed: 400 for an unreadable or invalid payload (with the reason), 500 if the catalog cannot be loaded.