API

Eventi webhook

Eventi webhook: quando vengono inviati, quale scope richiedono e cosa contiene il loro payload.

Ultimo aggiornamento:

Un evento webhook segnala al tuo sistema che qualcosa è cambiato. Ogni evento ha un nome, una versione e un payload. Lo scope indicato per un evento è lo scope del token che permette di sottoscriverlo.

Consegna

Ogni consegna è una richiesta POST con un corpo JSON della forma { type, tenantId, timestamp, data }; data è il payload indicato per l’evento. L’header X-PublicStatus-Event porta il nome dell’evento, X-PublicStatus-Delivery-Id un ID univoco per consegna e X-PublicStatus-Signature la firma sha256=<hex>: un HMAC-SHA256 calcolato sul corpo grezzo della richiesta, con il secret del webhook come chiave in testo UTF-8. Confronta con timingSafeEqual e rifiuta le richieste con una firma non corrispondente. Rispondi con uno stato 2xx entro 10 secondi. Una consegna fallita non viene ripetuta. Dopo 5 consegne fallite di fila il webhook viene disattivato finché non lo riattivi. L’indirizzo deve iniziare con https://; viene seguito un redirect. Le consegne verso indirizzi Slack e Discord usano il formato di quel servizio e non hanno firma.

Versioni

Aggiungere un campo facoltativo mantiene la versione. Una modifica incompatibile, come rimuovere o rinominare un campo o cambiarne il tipo, riceve una nuova versione.

Eventi

component.updated

È stato modificato un componente della pagina di stato.

  • Versione: 1
  • Scope richiesto: components:read
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì ID del componente
version number sì Versione del componente nota a chi ha chiamato
changes object sì Solo i campi modificati
changes.name string no Nuovo nome
changes.description string no Nuova descrizione
changes.status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” no Nuovo stato operativo
changes.parentComponentId string no ID del nuovo componente padre
changes.displayOrder number no Nuova posizione sulla pagina di stato
changes.showOnPage boolean no Se il componente è mostrato pubblicamente
changes.customFields object no Nuovi valori dei campi personalizzati

Payload di esempio

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

incident.created

È stato aperto un incidente sulla pagina di stato.

  • Versione: 1
  • Scope richiesto: incidents:read
Campo Tipo Obbligatorio Descrizione
title string sì Titolo dell’incidente
body string sì Testo del primo aggiornamento nella cronologia dell’incidente
severity “minor” | “major” | “critical” sì Gravità dell’incidente
componentIds array of string (uuid) sì ID dei componenti interessati
startedAt string (date-time) no Inizio dell’incidente, se indicato
sourceMonitorId string (uuid) no ID del monitor che ha aperto l’incidente automaticamente

Payload di esempio

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

incident.resolved

Un incidente è stato segnato come risolto.

  • Versione: 1
  • Scope richiesto: incidents:read
Campo Tipo Obbligatorio Descrizione
incidentId string (uuid) sì ID dell’incidente
body string sì Testo dell’aggiornamento finale

Payload di esempio

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

incident.updated

È stato aggiunto un aggiornamento a un incidente aperto.

  • Versione: 1
  • Scope richiesto: incidents:read
Campo Tipo Obbligatorio Descrizione
incidentId string (uuid) sì ID dell’incidente
body string sì Testo dell’aggiornamento
newStatus “investigating” | “identified” | “monitoring” | “resolved” no Nuovo stato, se l’aggiornamento lo cambia

Payload di esempio

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

maintenance.cancelled

È stata annullata una finestra di manutenzione.

  • Versione: 1
  • Scope richiesto: maintenance:read
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì ID della manutenzione
version number no Versione della manutenzione nota a chi ha chiamato

Payload di esempio

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

maintenance.completed

È stata completata una finestra di manutenzione.

  • Versione: 1
  • Scope richiesto: maintenance:read
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì ID della manutenzione
version number no Versione della manutenzione nota a chi ha chiamato

Payload di esempio

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

maintenance.scheduled

È stata pianificata una finestra di manutenzione.

  • Versione: 1
  • Scope richiesto: maintenance:read
Campo Tipo Obbligatorio Descrizione
title string sì Titolo della manutenzione
body string sì Testo dell’annuncio
scheduledStart string (date-time) sì Inizio previsto
scheduledEnd string (date-time) sì Fine prevista
componentIds array of string (uuid) sì ID dei componenti interessati

Payload di esempio

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

È iniziata una finestra di manutenzione pianificata.

  • Versione: 1
  • Scope richiesto: maintenance:read
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì ID della manutenzione
version number no Versione della manutenzione nota a chi ha chiamato

Payload di esempio

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