API

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
}