Open Status
External alert incidents

External alert incidents

Create and update incidents from external alert payloads.

Alert systems can drive the incident lifecycle in Status by posting an alert and its state. The endpoint takes two shapes: a normalized alert, and a provider's own webhook body for Status to normalize.

POST/api/external-alerts
Scope
incidents:write
Autorisatie
Bearer-API-sleutel
Snelheidslimiet
120 requests per minute
Herhaalde aanvragen
Idempotent on organization + provider + externalId

The normalized shape. provider and externalId together are a stable organization-scoped identity for the alert, which is what makes a repeated delivery a repeat rather than a second incident. Unknown fields are rejected.

Body
providerstringverplicht

Which system raised the alert. Half of the alert's identity.

regel1–80 characters, lowercased on the way in
externalIdstringverplicht

The provider's own identifier for this alert. The other half — send the stable one, not one generated per delivery.

regel1–200 characters
stateenumverplicht

Whether the condition is currently true. This is what drives the transition; see Lifecycle behavior.

een vanfiring, resolved
titlestringverplicht

Becomes the incident's title when the alert opens one.

regel3–120 characters
messagestringverplicht

The first public update on the incident.

regel3–2000 characters
severityenumoptioneel

The incident's impact level.

een vanminor, major, criticalstandaardmajor
monitorIdsstring[]optioneel

Monitors the alert concerns. Every one must belong to the key's organization.

standaard[]regelup to 100 UUIDs, deduplicated
labelsobjectoptioneel

Provider metadata, kept on the incident for responders and used for grouping. Values may be strings, numbers or booleans; nested objects are dropped.

standaard{}regelup to 20 entries; names 60 chars, values 200
occurredAtstringoptioneel

When the alert fired, if that differs from when you are delivering it.

standaardingestion timeregelISO 8601 with an offset
Body — provider shape
providerenumverplicht

Send the vendor's own payload and Status normalizes it into the same lifecycle. One webhook may carry several alerts, and each is applied in turn.

een vanalertmanager, grafana, sentry, datadog
payloadunknownverplicht

The raw webhook body, exactly as the provider sent it.

monitorIdsstring[]optioneel

Correlations applied to every alert in the payload.

standaard[]regelup to 100 UUIDs
201Incident opened
JSON
{
  "incident": {
    "id": "1f2e3d4c-5b6a-4788-9c0d-1e2f3a4b5c6d",
    "status": "investigating",
    "title": "Database unavailable",
    "severity": "critical"
  },
  "transition": "create"
}
200Existing incident

A firing alert on an already-open incident, or a resolve. transition is reopen, resolve or duplicate.

JSON
{
  "incident": { "id": "1f2e3d4c-…", "status": "resolved" },
  "transition": "resolve"
}
202Accepted, no incident

A resolve for something that was never open, an alert the grouping rules ignored, or a provider payload — which is applied as a batch and reports counts rather than one incident.

JSON
{ "accepted": 3, "results": [{ "transition": "create" }] }
400Rejected

Neither shape validated, a batch exceeded 100 alerts, or a correlated monitor does not belong to the organization.

429Rate limited

Counted per organization and key. Retry-After and the RateLimit-* headers are on the response.

Voorbeeldaanvraag
Bash
curl -X POST https://status.example.com/api/external-alerts \
  -H "Authorization: Bearer $STATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "alertmanager",
    "externalId": "PABC123",
    "state": "firing",
    "title": "Database unavailable",
    "message": "The primary connection check is failing.",
    "severity": "critical",
    "monitorIds": ["5a75c040-9383-4fe3-8c08-aa66c5f149d4"]
  }'

Lifecycle behavior

Ingestion is idempotent:

  • the first firing creates an Investigating incident;
  • another firing while active returns the existing incident without another update;
  • a resolved event resolves the active incident;
  • another resolved event is a no-op;
  • a later firing reopens the same incident, clears acknowledgement, and preserves its history;
  • a resolution received before any firing is acknowledged as ignored.

Every correlated monitor must belong to the key owner. Correlated status-page components are derived from those monitors, so the external incident appears on the same public surfaces as a manually or automatically declared incident. Timeline entries are public and attributed to the integration source.

External-alert ingestion is limited to 120 requests per minute per account. See API rate limits.

Group provider alerts

Use Incidents → Manage → Alert grouping to collapse noisy provider alerts into one incident. A rule can apply to one provider or all providers and match the normalized provider, state, severity, title, message, or labels.<name>. Conditions can nest all, any, and none groups and use equality, set, substring, prefix/suffix, regular-expression, numeric comparison, existence, and boolean operators.

A matching rule can keep one incident per alert or group alerts by selected labels for a bounded time window. Grouping makes the selected label values the stable correlation key; alerts missing those values cannot join an unrelated group. Rules can also inhibit a downstream alert when a selected dependency monitor is unhealthy. Lower numeric priority wins.

The wizard's Preview tab accepts sample provider webhook bodies and shows exactly which alerts would open an incident, join a group, resolve one, or be inhibited. Use it before wiring a sender to confirm field and label normalization.

Related documentation