Webhook-Ereignisse
Webhook-Ereignisse: wann sie ausgelöst werden, welchen Scope sie brauchen und was ihre Nutzlast enthält.
Stand:
Ein Webhook-Ereignis meldet deinem System, dass sich etwas geändert hat. Jedes Ereignis hat einen Namen, eine Version und eine Nutzlast. Der bei einem Ereignis genannte Scope ist der Token-Scope, der das Abonnieren erlaubt.
Zustellung
Jede Zustellung ist eine POST-Anfrage mit JSON-Body der Form { type, tenantId, timestamp, data }; data ist die beim Ereignis aufgeführte Nutzlast. Der Header X-PublicStatus-Event trägt den Ereignisnamen, X-PublicStatus-Delivery-Id eine eindeutige ID je Zustellung und X-PublicStatus-Signature die Signatur sha256=<hex>: ein HMAC-SHA256 über den rohen Request-Body, mit dem Webhook-Secret als UTF-8-Text als Schlüssel. Vergleiche mit timingSafeEqual und weise Anfragen mit nicht passender Signatur ab. Antworte innerhalb von 10 Sekunden mit einem 2xx-Status. Eine fehlgeschlagene Zustellung wird nicht wiederholt. Nach 5 fehlgeschlagenen Zustellungen in Folge wird der Webhook deaktiviert, bis du ihn wieder einschaltest. Die Adresse muss mit https:// beginnen; ein Redirect wird verfolgt. Zustellungen an Slack- und Discord-Adressen nutzen das Format des jeweiligen Dienstes und tragen keine Signatur.
Versionen
Ein neues optionales Feld behält die Version. Eine inkompatible Änderung, etwa ein entferntes oder umbenanntes Feld oder ein geänderter Typ, bekommt eine neue Version.
Ereignisse
component.updated
Eine Komponente der Statusseite wurde geändert.
- Version:
1 - Benötigter Scope:
components:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id |
string (uuid) | ja | ID der Komponente |
version |
number | ja | Version der Komponente, die der Aufrufer kannte |
changes |
object | ja | Nur die geänderten Felder |
changes.name |
string | nein | Neuer Name |
changes.description |
string | nein | Neue Beschreibung |
changes.status |
“operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” | nein | Neuer Betriebsstatus |
changes.parentComponentId |
string | nein | ID der neuen übergeordneten Komponente |
changes.displayOrder |
number | nein | Neue Position auf der Statusseite |
changes.showOnPage |
boolean | nein | Ob die Komponente öffentlich angezeigt wird |
changes.customFields |
object | nein | Neue Werte der eigenen Felder |
Beispiel-Nutzlast
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 2,
"changes": {
"description": "Slower than usual",
"status": "degraded-performance"
}
}
incident.created
Auf der Statusseite wurde ein Vorfall eröffnet.
- Version:
1 - Benötigter Scope:
incidents:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
title |
string | ja | Titel des Vorfalls |
body |
string | ja | Text des ersten Updates im Verlauf des Vorfalls |
severity |
“minor” | “major” | “critical” | ja | Schweregrad des Vorfalls |
componentIds |
array of string (uuid) | ja | IDs der betroffenen Komponenten |
startedAt |
string (date-time) | nein | Beginn des Vorfalls, falls angegeben |
sourceMonitorId |
string (uuid) | nein | ID des Monitors, der den Vorfall automatisch eröffnet hat |
Beispiel-Nutzlast
{
"title": "Elevated API errors",
"body": "We are investigating elevated error rates.",
"severity": "major",
"componentIds": [
"00000000-0000-4000-8000-000000000001"
]
}
incident.resolved
Ein Vorfall wurde als gelöst markiert.
- Version:
1 - Benötigter Scope:
incidents:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
incidentId |
string (uuid) | ja | ID des Vorfalls |
body |
string | ja | Text des abschließenden Updates |
Beispiel-Nutzlast
{
"incidentId": "00000000-0000-4000-8000-000000000001",
"body": "Error rates are back to normal."
}
incident.updated
Einem offenen Vorfall wurde ein Update hinzugefügt.
- Version:
1 - Benötigter Scope:
incidents:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
incidentId |
string (uuid) | ja | ID des Vorfalls |
body |
string | ja | Text des Updates |
newStatus |
“investigating” | “identified” | “monitoring” | “resolved” | nein | Neuer Status, falls das Update ihn ändert |
Beispiel-Nutzlast
{
"incidentId": "00000000-0000-4000-8000-000000000001",
"body": "The cause is identified.",
"newStatus": "identified"
}
maintenance.cancelled
Ein Wartungsfenster wurde abgesagt.
- Version:
1 - Benötigter Scope:
maintenance:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id |
string (uuid) | ja | ID der Wartung |
version |
number | nein | Version der Wartung, die der Aufrufer kannte |
Beispiel-Nutzlast
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 1
}
maintenance.completed
Ein Wartungsfenster wurde abgeschlossen.
- Version:
1 - Benötigter Scope:
maintenance:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id |
string (uuid) | ja | ID der Wartung |
version |
number | nein | Version der Wartung, die der Aufrufer kannte |
Beispiel-Nutzlast
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 2
}
maintenance.scheduled
Ein Wartungsfenster wurde geplant.
- Version:
1 - Benötigter Scope:
maintenance:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
title |
string | ja | Titel der Wartung |
body |
string | ja | Ankündigungstext |
scheduledStart |
string (date-time) | ja | Geplanter Beginn |
scheduledEnd |
string (date-time) | ja | Geplantes Ende |
componentIds |
array of string (uuid) | ja | IDs der betroffenen Komponenten |
Beispiel-Nutzlast
{
"title": "Database upgrade",
"body": "Short read-only period while we upgrade the database.",
"scheduledStart": "2026-01-15T09:30:00.000Z",
"scheduledEnd": "2026-01-15T09:30:00.000Z",
"componentIds": [
"00000000-0000-4000-8000-000000000001"
]
}
maintenance.started
Ein geplantes Wartungsfenster hat begonnen.
- Version:
1 - Benötigter Scope:
maintenance:read
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id |
string (uuid) | ja | ID der Wartung |
version |
number | nein | Version der Wartung, die der Aufrufer kannte |
Beispiel-Nutzlast
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 1
}