API

Événements webhook

Événements webhook : quand ils sont envoyés, quel scope ils exigent et ce que contient leur charge utile.

Dernière mise à jour :

Un événement webhook informe votre système qu’une chose a changé. Chaque événement a un nom, une version et une charge utile. Le scope indiqué pour un événement est le scope de jeton qui permet de s’y abonner.

Livraison

Chaque livraison est une requête POST avec un corps JSON de la forme { type, tenantId, timestamp, data } ; data est la charge utile indiquée pour l’événement. L’en-tête X-PublicStatus-Event porte le nom de l’événement, X-PublicStatus-Delivery-Id un identifiant unique par livraison et X-PublicStatus-Signature la signature sha256=<hex> : un HMAC-SHA256 calculé sur le corps brut de la requête, avec le secret du webhook comme clé en texte UTF-8. Comparez avec timingSafeEqual et rejetez les requêtes dont la signature ne correspond pas. Répondez par un statut 2xx en 10 secondes. Une livraison échouée n’est pas renvoyée. Après 5 livraisons échouées d’affilée, le webhook est désactivé jusqu’à ce que vous le réactiviez. L’adresse doit commencer par https:// ; une redirection est suivie. Les livraisons vers des adresses Slack et Discord utilisent le format de ce service et ne portent pas de signature.

Versions

Ajouter un champ facultatif conserve la version. Un changement incompatible, comme la suppression ou le renommage d’un champ ou le changement de son type, reçoit une nouvelle version.

Événements

component.updated

Un composant de la page de statut a été modifié.

  • Version: 1
  • Scope requis: components:read
Champ Type Obligatoire Description
id string (uuid) oui Identifiant du composant
version number oui Version du composant connue de l’appelant
changes object oui Uniquement les champs modifiés
changes.name string non Nouveau nom
changes.description string non Nouvelle description
changes.status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” non Nouveau statut opérationnel
changes.parentComponentId string non Identifiant du nouveau composant parent
changes.displayOrder number non Nouvelle position sur la page de statut
changes.showOnPage boolean non Si le composant est affiché publiquement
changes.customFields object non Nouvelles valeurs des champs personnalisés

Exemple de charge utile

{
  "id": "00000000-0000-4000-8000-000000000001",
  "version": 2,
  "changes": {
    "description": "Slower than usual",
    "status": "degraded-performance"
  }
}

incident.created

Un incident a été ouvert sur la page de statut.

  • Version: 1
  • Scope requis: incidents:read
Champ Type Obligatoire Description
title string oui Titre de l’incident
body string oui Texte de la première mise à jour dans la chronologie de l’incident
severity “minor” | “major” | “critical” oui Gravité de l’incident
componentIds array of string (uuid) oui Identifiants des composants concernés
startedAt string (date-time) non Début de l’incident, s’il est indiqué
sourceMonitorId string (uuid) non Identifiant du moniteur qui a ouvert l’incident automatiquement

Exemple de charge utile

{
  "title": "Elevated API errors",
  "body": "We are investigating elevated error rates.",
  "severity": "major",
  "componentIds": [
    "00000000-0000-4000-8000-000000000001"
  ]
}

incident.resolved

Un incident a été marqué comme résolu.

  • Version: 1
  • Scope requis: incidents:read
Champ Type Obligatoire Description
incidentId string (uuid) oui Identifiant de l’incident
body string oui Texte de la mise à jour finale

Exemple de charge utile

{
  "incidentId": "00000000-0000-4000-8000-000000000001",
  "body": "Error rates are back to normal."
}

incident.updated

Une mise à jour a été ajoutée à un incident ouvert.

  • Version: 1
  • Scope requis: incidents:read
Champ Type Obligatoire Description
incidentId string (uuid) oui Identifiant de l’incident
body string oui Texte de la mise à jour
newStatus “investigating” | “identified” | “monitoring” | “resolved” non Nouveau statut, si la mise à jour le modifie

Exemple de charge utile

{
  "incidentId": "00000000-0000-4000-8000-000000000001",
  "body": "The cause is identified.",
  "newStatus": "identified"
}

maintenance.cancelled

Une fenêtre de maintenance a été annulée.

  • Version: 1
  • Scope requis: maintenance:read
Champ Type Obligatoire Description
id string (uuid) oui Identifiant de la maintenance
version number non Version de la maintenance connue de l’appelant

Exemple de charge utile

{
  "id": "00000000-0000-4000-8000-000000000001",
  "version": 1
}

maintenance.completed

Une fenêtre de maintenance a été terminée.

  • Version: 1
  • Scope requis: maintenance:read
Champ Type Obligatoire Description
id string (uuid) oui Identifiant de la maintenance
version number non Version de la maintenance connue de l’appelant

Exemple de charge utile

{
  "id": "00000000-0000-4000-8000-000000000001",
  "version": 2
}

maintenance.scheduled

Une fenêtre de maintenance a été planifiée.

  • Version: 1
  • Scope requis: maintenance:read
Champ Type Obligatoire Description
title string oui Titre de la maintenance
body string oui Texte d’annonce
scheduledStart string (date-time) oui Début prévu
scheduledEnd string (date-time) oui Fin prévue
componentIds array of string (uuid) oui Identifiants des composants concernés

Exemple de charge utile

{
  "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

Une fenêtre de maintenance planifiée a commencé.

  • Version: 1
  • Scope requis: maintenance:read
Champ Type Obligatoire Description
id string (uuid) oui Identifiant de la maintenance
version number non Version de la maintenance connue de l’appelant

Exemple de charge utile

{
  "id": "00000000-0000-4000-8000-000000000001",
  "version": 1
}