Webhook version 3.0

Webhook version 3.0

StatusGator’s webhook version 3.0 supports notifications for monitor status changes, Early Warning Signals, and confirmed outage reports submitted through your status page.

Each payload includes a type field that identifies the event. Use this field to determine how to process the request.

Event types

Event	Payload type	When it’s sent
Status changes	StatusChange	A monitor’s overall status or component status changes.
Early Warning Signals	EarlyWarningSignal	StatusGator detects a possible outage before official provider acknowledgment.
User outage reports	OutageReport	A report submitted through your board’s status page is confirmed.

New webhooks have all three events enabled by default. Existing webhooks continue receiving status changes and Early Warning Signals. To receive outage reports, enable User outage reports in the webhook’s settings.

Choose which events to receive

1. Open the board where you want to configure the webhook.
2. Go to Integrations → Webhook.
3. Under Event types, select the events you want to receive.
4. Save your settings.

For initial setup instructions, see Connect StatusGator to Webhooks.

Version compatibility: Outage report events always use the v3 payload format, regardless of the version selected in your webhook settings.

Early Warning Signal payload

An EarlyWarningSignal event notifies you of a possible outage detected by StatusGator.

{
  "type": "EarlyWarningSignal",
  "recorded_at": "2025-01-29T20:54:48Z",
  "service": {
    "id": "M1xKnyloHR",
    "name": "Resideo",
    "slug": "resideo",
    "home_page_url": "<https://resideo.com>",
    "status_page_url": "<https://status.resideo.com>",
    "icon_url": "<https://favicons.statusgator.com/resideo.png>",
    "landing_page_url": "<https://statusgator.com/services/resideo>"
  },
  "monitor": {
    "id": "uZoM2YK1rn",
    "type": "ServiceMonitor",
    "display_name": "Resideo",
    "icon_url": "<https://favicons.statusgator.com/resideo.png>"
  },
  "board": {
    "id": "X1iMbb5HTm",
    "name": "123"
  },
  "summary": "Service outage",
  "yes_vote_url": "<https://statusgator.com/signal_alerts/UkLWZg9DAJ/confirm>",
  "no_vote_url": "<https://statusgator.com/signal_alerts/UkLWZg9DAJ/deny>"
}

Status change payload

A StatusChange event includes the monitor’s current and previous status, incident information when available, and any reported component status changes.

{
  "type": "StatusChange",
  "recorded_at": "2025-07-17T02:20:45Z",
  "service": {
    "id": "OUQJLhNcSb",
    "name": "OpenAI",
    "slug": "openai",
    "home_page_url": "<https://openai.com>",
    "status_page_url": "<https://status.openai.com>",
    "icon_url": "<https://favicons.statusgator.com/openai.png>",
    "landing_page_url": "<https://statusgator.com/services/openai>"
  },
  "monitor": {
    "id": "UIMPLWZg9D",
    "type": "ServiceMonitor",
    "display_name": "OpenAI",
    "icon_url": "<https://favicons.statusgator.com/openai.png>"
  },
  "board": {
    "id": "Pwg0NMcnNF",
    "name": "Demo 2"
  },
  "status": "up",
  "previous_status": "down",
  "message": "Elevated Error Rate on ChatGPT",
  "details": "We have identified that users are experiencing elevated errors for the impacted services. We are working on implementing a mitigation.",
  "component_status_changes": [
    {
      "group_name": "APIs",
      "name": "Chat",
      "last_status": "up",
      "current_status": "down"
    },
    {
      "group_name": "APIs",
      "name": "Images",
      "last_status": "up",
      "current_status": "down"
    }
  ]
}

Status change and Early Warning Signal fields

The following fields apply to StatusChange and EarlyWarningSignal events. Availability depends on the event and monitor type.

Event fields

Field	Description
type	Identifies the event as StatusChange or EarlyWarningSignal.
recorded_at	Detection time, expressed as an ISO 8601 UTC timestamp.
summary	For Early Warning Signals, a short description based on received outage reports.
yes_vote_url	For Early Warning Signals, the URL for reporting that you are experiencing the issue.
no_vote_url	For Early Warning Signals, the URL for reporting that you are not experiencing the issue.

Service fields

The service object accompanies service monitor events.

Field	Description
service.id	Identifier for the provider in StatusGator.
service.name	Provider name in the StatusGator directory.
service.slug	URL-compatible identifier for the provider.
service.home_page_url	Provider website, when available.
service.status_page_url	Provider’s official status page, when available.
service.icon_url	Default provider icon.
service.landing_page_url	Provider’s StatusGator page, where users can view status and report problems.

Board and monitor fields

Field	Description
board	Identifies the board associated with the notification.
board.id	Board identifier.
board.name	Board name.
monitor	Identifies the monitor associated with the notification.
monitor.id	Monitor identifier.
monitor.type	Monitor class, such as ServiceMonitor, WebsiteMonitor, or PingMonitor.
monitor.display_name	Your monitor’s display name, including any customization.
monitor.icon_url	Your monitor’s icon, including any customization.
monitor.url	Monitored URL, included for website monitors.
monitor.host	Monitored host, included for ping monitors.

Status change fields

Field	Description
status	Resulting monitor status: up, down, warn, or maintenance.
previous_status	Monitor status before the change.
message	Brief incident title supplied by the provider, when available.
details	Additional incident text supplied by the provider, when available.
component_status_changes	Component changes reported for a service monitor, when available.
component_status_changes[].group_name	Affected component’s group.
component_status_changes[].name	Affected component’s name.
component_status_changes[].last_status	Component status before the change.
component_status_changes[].current_status	Component status after the change.

User outage report payload

An OutageReport event is sent when an outage report submitted through your board’s status page is confirmed.

The payload includes the affected service, selected components, the reporter’s comment and email address if provided, and their approximate location. The reporter’s IP address is never included.

Outage reports use the same signing secret, custom headers, delivery logs, and retries as your other webhook events.

{
  "type": "OutageReport",
  "recorded_at": "2026-10-15T14:22:09Z",
  "board": {
    "id": "X1iMbb5HTm",
    "name": "Production"
  },
  "id": "lpZ4nQy7Hk",
  "service": {
    "id": "OUQJLhNcSb",
    "name": "OpenAI",
    "icon_url": "<https://favicons.statusgator.com/openai.png>",
    "official": true
  },
  "monitor": {
    "id": "UIMPLWZg9D",
    "name": "OpenAI",
    "monitor_type": "ServiceMonitor",
    "icon_url": "<https://favicons.statusgator.com/openai.png>"
  },
  "summary": {
    "id": "5rX2kQ",
    "description": "Service down"
  },
  "comment": "I can't reach ChatGPT.",
  "email": "reporter@example.com",
  "components": [
    {
      "id": "9aB3cD1eFg",
      "name": "Chat",
      "group_name": "APIs"
    }
  ],
  "location": {
    "city": "Seattle",
    "region": "Washington",
    "country": "United States",
    "country_code": "US"
  },
  "confirmed_at": "2026-10-15T14:22:09.123Z",
  "created_at": "2026-10-15T14:20:51.880Z"
}

User outage report fields

Report fields appear directly in the JSON body, without a separate report wrapper. A nullable field can contain null.

Field	Type	Description
type	string	Always "OutageReport".
recorded_at	string	When the report was confirmed, in ISO 8601 UTC format.
board	object	The board whose status page received the report.
board.id	string	Public ID of the board.
board.name	string	Name of the board.
id	string	Public ID of the outage report.
service	object	The service being reported.
service.id	string	Public ID of the service.
service.name	string	Name of the service.
service.icon_url	string, nullable	URL of the service icon.
service.official	boolean	Whether this is an official StatusGator service.
monitor	object, nullable	The monitor on your board for this service. null if the board no longer has it.
monitor.id	string	Public ID of the monitor.
monitor.name	string	Display name of the monitor.
monitor.monitor_type	string	One of ServiceMonitor, WebsiteMonitor, PingMonitor, or CustomMonitor.
monitor.icon_url	string, nullable	URL of the monitor icon.
summary	object, nullable	The problem category, selected by the reporter or derived from their comment.
summary.id	string	ID of the category.
summary.description	string	Name of the category, such as "Service down".
comment	string, nullable	The reporter’s description of the problem.
email	string, nullable	The reporter’s email address, or null if none was provided.
components	array	Components the reporter marked as affected. May be empty.
components[].id	string	Public ID of the component.
components[].name	string	Name of the component.
components[].group_name	string, nullable	The component’s group.
location	object	The reporter’s approximate location, determined from their IP address.
location.city	string, nullable	City.
location.region	string, nullable	Region or state.
location.country	string, nullable	Country name.
location.country_code	string, nullable	ISO 3166-1 alpha-2 country code, such as "US".
confirmed_at	string	When the report was confirmed, in ISO 8601 format.
created_at	string	When the report was submitted, in ISO 8601 format.

Differences between event payloads

Check type before reading event-specific fields.

Field	Status changes and Early Warning Signals	User outage reports
Monitor name	monitor.display_name	monitor.name
Monitor type	monitor.type	monitor.monitor_type
summary	A string for Early Warning Signals.	An object containing id and description, or null.
recorded_at	When StatusGator detected the event.	When the report was confirmed.
monitor	Describes the monitor associated with the event.	Can be null if the board no longer has the monitor.

Verify the request signature

Every request includes an X-Signature header containing a hex-encoded HMAC-SHA256 signature. The signature is generated from the raw request body using your webhook’s signing secret.

Verify the signature before processing the payload. Use the raw request body before JSON parsing.

Node.js example

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  if (
    typeof signature !== "string" ||
    !/^[a-f0-9]{64}$/i.test(signature)
  ) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest();

  const received = Buffer.from(signature, "hex");

  return crypto.timingSafeEqual(received, expected);
}

Outage report requests also include these headers:

Content-Type: application/json
X-Webhook-Version: 3.0

Retrieve outage reports through the API

You can also fetch confirmed outage reports through API v3:

GET /api/v3/boards/{board_id}/outage_reports?since=2026-10-15T00:00:00Z

The endpoint returns confirmed reports from the board’s status pages, newest first, with 25 reports per page.

The optional since parameter accepts an ISO 8601 timestamp and includes reports confirmed at or after that time. Follow pagination to retrieve all matching reports.

Each report has the same report fields as the webhook payload, without type, recorded_at, and board.

See the API documentation for authentication and request details.