Notification Channels Reference

Overview

Notifications in OpenStatus provide real-time alerts regarding changes in monitor status, such as recovery from an outage or detection of a new failure. By default, no notification channels are configured in a new workspace. Users must configure and enable specific channels to receive alerts.

Notification Channels

Each notification channel requires specific configuration parameters to enable alert delivery.

Slack

Integrates with Slack to send alerts to a designated channel.

Configuration:

Incoming Webhook URL: (Required) A Slack incoming webhook URL where notifications will be posted.

Email

Sends alerts directly to a specified email address.

Configuration:

Email Address: (Required) The recipient’s email address.

Discord

Delivers alerts to a Discord channel via a webhook.

Configuration:

Webhook URL: (Required) A Discord webhook URL for the target channel. Example: https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890

Google Chat

Sends notifications to a Google Chat space.

Configuration:

Webhook URL: (Required) A Google Chat webhook URL for the target space.

SMS

Sends alerts as SMS messages to a mobile phone number.

Configuration:

Phone Number: (Required) The recipient’s phone number in international format (e.g., +14155552671).

Note: SMS delivery can vary by country due to provider routing. Contact support if delivery issues are encountered. WhatsApp notifications may be an alternative.

Sends alerts as WhatsApp messages to a mobile phone number.

Configuration:

Phone Number: (Required) The recipient’s phone number in international format (e.g., +14155552671).

Delivers alerts to a specified Telegram chat.

Configuration:

Chat ID: (Required) The unique identifier for the Telegram chat. This typically requires manual retrieval; users can ask @raw_info_bot for their chat ID.

Bot ID: The official OpenStatus Telegram bot ID is @openstatushq_bot.

Webhook

Sends HTTP POST requests to a custom endpoint with a JSON payload.

Configuration:

URL: (Required) The endpoint URL to which the webhook payload will be sent.
Headers: (Optional) Custom HTTP headers to include with the webhook request (key-value pairs).

Notification Payloads

Webhook notifications utilize specific JSON payloads for different monitor status changes.

Monitor Recovery Payload

Sent when a monitor recovers from a degraded or error state.

{
  "monitor": {
    "id": 1,
    "name": "test",
    "url": "http://openstat.us"
  },
  "cronTimestamp": 1744023705307,
  "status": "recovered",
  "statusCode": 200,
  "latency": 1337
}

Payload Fields:

Field	Type	Description
`monitor.id`	`number`	Unique identifier of the monitor.
`monitor.name`	`string`	Name of the monitor.
`monitor.url`	`string`	The URL or URI being monitored.
`cronTimestamp`	`number`	Timestamp of the check execution in milliseconds since epoch.
`status`	`string`	Indicates the monitor status: `"recovered"`.
`statusCode`	`number`	(Optional) HTTP status code returned by the monitored service.
`latency`	`number`	(Optional) Time taken to complete the check in milliseconds.

Monitor Failure Payload

Sent when a monitor enters an error or degraded state.

{
  "monitor": {
    "id": 1,
    "name": "test",
    "url": "http://openstat.us"
  },
  "cronTimestamp": 1744023705307,
  "status": "error",
  "errorMessage": "Connection refused"
}

Payload Fields:

Field	Type	Description
`monitor.id`	`number`	Unique identifier of the monitor.
`monitor.name`	`string`	Name of the monitor.
`monitor.url`	`string`	The URL or URI being monitored.
`cronTimestamp`	`number`	Timestamp of the check execution in milliseconds since epoch.
`status`	`string`	Indicates the monitor status: `"degraded"` or `"error"`.
`errorMessage`	`string`	(Optional) A description of the error encountered during the check.

Zod Schema

The validation schema for webhook payloads:

import { z } from "zod";

export const PayloadSchema = z.object({
  monitor: z.object({
    id: z.number(),
    name: z.string(),
    url: z.string(),
  }),
  cronTimestamp: z.number(),
  status: z.enum(["degraded", "error", "recovered"]),
  statusCode: z.number().optional(),
  latency: z.number().optional(),
  errorMessage: z.string().optional(),
});

OpsGenie

Integrates with OpsGenie for incident management.

Configuration:

API Key: (Required) An API key obtained from your OpsGenie account.

PagerDuty

Integrates with PagerDuty for incident alerting.

Configuration:

Integration Steps: (Required) Follow the specific integration steps provided within the PagerDuty workflow to set up this channel.

Ntfy

Sends notifications to an Ntfy topic.

Configuration:

Ntfy Topic: (Required) The topic name to which notifications will be published.
Custom Server URL: (Optional) The URL of a custom Ntfy server if not using the default.
Bearer Token: (Optional) An authentication token for accessing the Ntfy server.

Monitor Data Collected - Details on all metrics collected by monitors.
Incident Reference - Information about incident creation and management.

Notification Channels Reference

Overview