API

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
}