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
}