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
}