Eventos de webhook
Eventos de webhook: cuándo se envían, qué scope necesitan y qué contiene su carga.
Última actualización:
Un evento de webhook avisa a tu sistema de que algo ha cambiado. Cada evento tiene un nombre, una versión y una carga. El scope indicado en un evento es el scope de token que permite suscribirse a él.
Entrega
Cada entrega es una petición POST con un cuerpo JSON de la forma { type, tenantId, timestamp, data }; data es la carga indicada en el evento. La cabecera X-PublicStatus-Event lleva el nombre del evento, X-PublicStatus-Delivery-Id un ID único por entrega y X-PublicStatus-Signature la firma sha256=<hex>: un HMAC-SHA256 sobre el cuerpo bruto de la petición, con el secret del webhook como clave en texto UTF-8. Compara con timingSafeEqual y rechaza las peticiones cuya firma no coincida. Responde con un estado 2xx en 10 segundos. Una entrega fallida no se reintenta. Tras 5 entregas fallidas seguidas el webhook se desactiva hasta que lo vuelvas a activar. La dirección debe empezar por https://; se sigue una redirección. Las entregas a direcciones de Slack y Discord usan el formato de ese servicio y no llevan firma.
Versiones
Añadir un campo opcional mantiene la versión. Un cambio incompatible, como quitar o renombrar un campo o cambiar su tipo, recibe una versión nueva.
Eventos
component.updated
Se modificó un componente de la página de estado.
- Versión:
1 - Scope necesario:
components:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id |
string (uuid) | sí | ID del componente |
version |
number | sí | Versión del componente que conocía quien llamó |
changes |
object | sí | Solo los campos modificados |
changes.name |
string | no | Nombre nuevo |
changes.description |
string | no | Descripción nueva |
changes.status |
“operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” | no | Estado operativo nuevo |
changes.parentComponentId |
string | no | ID del nuevo componente superior |
changes.displayOrder |
number | no | Posición nueva en la página de estado |
changes.showOnPage |
boolean | no | Si el componente se muestra públicamente |
changes.customFields |
object | no | Valores nuevos de los campos personalizados |
Carga de ejemplo
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 2,
"changes": {
"description": "Slower than usual",
"status": "degraded-performance"
}
}
incident.created
Se abrió una incidencia en la página de estado.
- Versión:
1 - Scope necesario:
incidents:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
title |
string | sí | Título de la incidencia |
body |
string | sí | Texto de la primera actualización en la cronología de la incidencia |
severity |
“minor” | “major” | “critical” | sí | Gravedad de la incidencia |
componentIds |
array of string (uuid) | sí | ID de los componentes afectados |
startedAt |
string (date-time) | no | Inicio de la incidencia, si se indicó |
sourceMonitorId |
string (uuid) | no | ID del monitor que abrió la incidencia automáticamente |
Carga de ejemplo
{
"title": "Elevated API errors",
"body": "We are investigating elevated error rates.",
"severity": "major",
"componentIds": [
"00000000-0000-4000-8000-000000000001"
]
}
incident.resolved
Una incidencia se marcó como resuelta.
- Versión:
1 - Scope necesario:
incidents:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
incidentId |
string (uuid) | sí | ID de la incidencia |
body |
string | sí | Texto de la actualización final |
Carga de ejemplo
{
"incidentId": "00000000-0000-4000-8000-000000000001",
"body": "Error rates are back to normal."
}
incident.updated
Se añadió una actualización a una incidencia abierta.
- Versión:
1 - Scope necesario:
incidents:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
incidentId |
string (uuid) | sí | ID de la incidencia |
body |
string | sí | Texto de la actualización |
newStatus |
“investigating” | “identified” | “monitoring” | “resolved” | no | Nuevo estado, si la actualización lo cambia |
Carga de ejemplo
{
"incidentId": "00000000-0000-4000-8000-000000000001",
"body": "The cause is identified.",
"newStatus": "identified"
}
maintenance.cancelled
Se canceló una ventana de mantenimiento.
- Versión:
1 - Scope necesario:
maintenance:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id |
string (uuid) | sí | ID del mantenimiento |
version |
number | no | Versión del mantenimiento que conocía quien llamó |
Carga de ejemplo
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 1
}
maintenance.completed
Se completó una ventana de mantenimiento.
- Versión:
1 - Scope necesario:
maintenance:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id |
string (uuid) | sí | ID del mantenimiento |
version |
number | no | Versión del mantenimiento que conocía quien llamó |
Carga de ejemplo
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 2
}
maintenance.scheduled
Se programó una ventana de mantenimiento.
- Versión:
1 - Scope necesario:
maintenance:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
title |
string | sí | Título del mantenimiento |
body |
string | sí | Texto del anuncio |
scheduledStart |
string (date-time) | sí | Inicio previsto |
scheduledEnd |
string (date-time) | sí | Fin prevista |
componentIds |
array of string (uuid) | sí | ID de los componentes afectados |
Carga de ejemplo
{
"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
Comenzó una ventana de mantenimiento programada.
- Versión:
1 - Scope necesario:
maintenance:read
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id |
string (uuid) | sí | ID del mantenimiento |
version |
number | no | Versión del mantenimiento que conocía quien llamó |
Carga de ejemplo
{
"id": "00000000-0000-4000-8000-000000000001",
"version": 1
}