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. Example: https://hooks.slack.com/services/XXX/YYY/ZZZ

You can download the openstatus logo to add a custom logo.

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

You can download the openstatus logo to add a custom logo.

Grafana OnCall IRM

Sends notifications to a Grafana OnCall IRM.

Configuration:

Webhook URL: (Required) A Grafana OnCall IRM webhook URL.

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 Payload

Every webhook notification — error, degraded, and recovered — uses the same flat JSON payload. statusCode, latency, and errorMessage are optional on every status; the sender includes whichever apply to the check.

{
  "monitor": {
    "id": 1,
    "name": "test",
    "url": "http://openstat.us"
  },
  "cronTimestamp": 1744023705307,
  "status": "error",
  "statusCode": 500,
  "latency": 1337,
  "errorMessage": "Internal Server Error"
}

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`	Monitor status: `"degraded"`, `"error"`, or `"recovered"`.
`statusCode`	`number`	(Optional) HTTP status code returned by the monitored service.
`latency`	`number`	(Optional) Time taken to complete the check in milliseconds.
`errorMessage`	`string`	(Optional) A description of the error encountered during the check.

Authentication

Webhook requests carry no payload signature or HMAC. The only verification mechanism is the custom headers you configure (e.g. a shared-secret header such as Authorization or x-webhook-secret) — validate one of those on your endpoint.

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.

Incident Reference - Information about incident creation and management.

Notification Channels Reference

Overview