Skip to content

Open-source status page, incident response and uptime monitoring

6.3 KB
Raw Blame
---
category: Reference
title: Notification Channels Reference
description: Technical specification for openstatus notification channels and alert payloads.
---

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. You 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](https://api.slack.com/incoming-webhooks) where notifications will be posted. Example: `https://hooks.slack.com/services/XXX/YYY/ZZZ`.

You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/openstatus.jpeg) 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](https://support.discord.com/hc/en-us/articles/228383668) for the target channel. Example: `https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`.

You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/openstatus.jpeg) 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](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/configure/integrations/webhooks/incoming-webhooks/oncall-webhooks/).

### Google Chat

Sends notifications to a Google Chat space.

**Configuration:**

- **Webhook URL** (required) — a [Google Chat webhook URL](https://developers.google.com/workspace/chat/quickstart/webhooks) for the target space.

### Microsoft Teams

Sends notifications to a Microsoft Teams channel through a Power Automate workflow.

**Configuration:**

- **Webhook URL** (required) — the URL of a Power Automate *"When a Teams webhook request is received"* workflow. Example: `https://prod-00.westeurope.logic.azure.com:443/workflows/abc/triggers/manual/paths/invoke`.

### WhatsApp

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`).

### Telegram

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.

```json
{
  "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:

```ts
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.
- **Region** (required) — the OpsGenie API region your account lives in: `us` or `eu`.

### PagerDuty

Integrates with PagerDuty for incident alerting.

**Configuration:**

- **Integration key** (required) — the Events API v2 integration key for your PagerDuty service. The dashboard walks you through the PagerDuty connect flow, which fills this in for you.

### 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.

## Related resources

- **[Incident reference](/docs/reference/incident)** — information about incident creation and management.