API

Webhook events

Webhook events: when they fire, which scope they need and what their payload contains.

Last updated:

A webhook event tells your system that something changed. Every event has a name, a version and a payload. The scope listed for an event is the token scope that allows subscribing to it.

Delivery

Every delivery is a POST request with a JSON body of the form { type, tenantId, timestamp, data }; data is the payload listed for the event. The X-PublicStatus-Event header carries the event name, X-PublicStatus-Delivery-Id a unique ID per delivery, and X-PublicStatus-Signature the signature sha256=<hex>: an HMAC-SHA256 over the raw request body, keyed with the webhook secret as a UTF-8 string. Compare it with timingSafeEqual and reject a request whose signature does not match. Answer with a 2xx status within 10 seconds. A failed delivery is not retried. After 5 failed deliveries in a row the webhook is deactivated until you switch it on again. The address must start with https://; one redirect is followed. Deliveries to Slack and Discord addresses use the format of that service and carry no signature.

Versions

Adding an optional field keeps the version. A breaking change, such as removing or renaming a field or changing its type, gets a new version.

Events

component.updated

A component of the status page was changed.

  • Version: 1
  • Required scope: components:read
Field Type Required Description
id string (uuid) yes ID of the component
version number yes Version of the component the caller saw
changes object yes Only the fields that were changed
changes.name string no New name
changes.description string no New description
changes.status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” no New operational status
changes.parentComponentId string no ID of the new parent component
changes.displayOrder number no New position on the status page
changes.showOnPage boolean no Whether the component is shown publicly
changes.customFields object no New custom field values

Example payload

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

incident.created

An incident was opened on the status page.

  • Version: 1
  • Required scope: incidents:read
Field Type Required Description
title string yes Title of the incident
body string yes Text of the first update in the incident timeline
severity “minor” | “major” | “critical” yes How severe the incident is
componentIds array of string (uuid) yes IDs of the components the incident affects
startedAt string (date-time) no When the incident started, if given
sourceMonitorId string (uuid) no ID of the monitor that opened the incident automatically

Example payload

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

incident.resolved

An incident was marked as resolved.

  • Version: 1
  • Required scope: incidents:read
Field Type Required Description
incidentId string (uuid) yes ID of the incident
body string yes Text of the final update

Example payload

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

incident.updated

An update was added to an open incident.

  • Version: 1
  • Required scope: incidents:read
Field Type Required Description
incidentId string (uuid) yes ID of the incident
body string yes Text of the update
newStatus “investigating” | “identified” | “monitoring” | “resolved” no New status, if the update changes it

Example payload

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

maintenance.cancelled

A maintenance window was cancelled.

  • Version: 1
  • Required scope: maintenance:read
Field Type Required Description
id string (uuid) yes ID of the maintenance window
version number no Version of the maintenance window the caller saw

Example payload

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

maintenance.completed

A maintenance window was completed.

  • Version: 1
  • Required scope: maintenance:read
Field Type Required Description
id string (uuid) yes ID of the maintenance window
version number no Version of the maintenance window the caller saw

Example payload

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

maintenance.scheduled

A maintenance window was scheduled.

  • Version: 1
  • Required scope: maintenance:read
Field Type Required Description
title string yes Title of the maintenance window
body string yes Announcement text
scheduledStart string (date-time) yes Planned start
scheduledEnd string (date-time) yes Planned end
componentIds array of string (uuid) yes IDs of the components the maintenance affects

Example payload

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

A scheduled maintenance window started.

  • Version: 1
  • Required scope: maintenance:read
Field Type Required Description
id string (uuid) yes ID of the maintenance window
version number no Version of the maintenance window the caller saw

Example payload

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