Alerts

When an alert goes out

Each change of state sends one alert: when a monitor goes down, when it turns slow, and when it is back, with the time, the reason, and how long it was out. A single failed check sends nothing: it takes two in a row, each checked again in its region. On Hobby and Pro an alert says which regions it is down from, "API is down from North America", and another goes out when the outage spreads to other regions or leaves some. A repeat interval on the settings page sends a "still down" notice every so many minutes while an outage lasts; by email at most every 30 minutes and 24 times in one outage. Nothing is sent during a maintenance window. A down alert says since when and from which locations the failure was seen, and the email's button opens the page in the dashboard. An incident you opened, or have posted to, that goes an hour without an update sends a reminder to post one by email, Slack, Discord, Microsoft Teams, Telegram, Pushover and ntfy, and another each hour it stays quiet, for a day at most.

On Pro, a component that follows a vendor's status page sends an alert by email, Slack, Discord, Microsoft Teams, Telegram, Pushover and ntfy when the vendor reports an outage or trouble, and when it reports things working again, with the vendor's open incidents. Pointing a component at a vendor sends nothing; only later changes do.

Destinations

An account keeps one list of alert destinations, under Account, Alerts, and each page ticks the ones its alerts go to on its own Settings, Alerts, where a new one can also be added. The account's own address is ticked on every new page. Each other person on the team has a box too, off until ticked, and needs no link. Another address gets a link first, and alerts go there once it is opened. Emails come from [email protected], which is worth allow-listing. Outlook, Hotmail and other Microsoft mailboxes may put StatOSS email in Junk for now. On Hobby and Pro a page can also post to Slack (Connect Slack picks a channel in Slack; a webhook URL works too), Discord, a Microsoft Teams channel (a workflow URL) and Telegram (your own bot), page through PagerDuty (an Events API v2 integration key; a monitor going down triggers an incident that its recovery resolves) or Opsgenie (an API integration key, with an EU switch; the same open and close), push to a phone through Pushover (an application token and a user key) or ntfy (a topic URL and an optional token), and post to a webhook of your own. Tokens and keys are stored encrypted, and the dashboard names a destination by its chat, the last four of its key, or its host. Alerts can be turned off per page, and "Send a test alert" tries every destination the page ticked and says which ones took it; each destination on the account's list has a test of its own. A page sends at most five test emails an hour.

Microsoft Teams

Each alert is a card in the channel with a link to the page.

1. In Teams, open Workflows and create one from the template "Post to a channel when a webhook request is received".
2. Pick the team and channel, and copy the URL it shows.
3. In StatOSS, under Account, Alerts, choose Microsoft Teams, paste the URL, tick the pages, and add it.
4. Press "Send a test".

A workflow that was deleted or turned off answers with a refusal, which the delivery record shows; make a new one and change the URL.

Telegram

Alerts come from a bot of your own, to a person, a group, or a channel. Each one has the alert in bold and a link to the page.

1. In Telegram, message @BotFather, send /newbot, and copy the token it gives.
2. Add the bot to the group or channel; in a channel it needs to be an admin that can post. For alerts to yourself, send the bot a message first.
3. Find the chat ID: send a message in the chat, then open https://api.telegram.org/bot<token>/getUpdates and read chat.id. A group or channel ID starts with a minus sign. A public channel can use its @name instead.
4. In StatOSS, under Account, Alerts, choose Telegram, paste the token and the chat ID, and add it. Press "Send a test".

When Telegram refuses an alert, the test and the delivery record say why: the chat was not found, the bot was blocked or removed, or the token is not valid.

Pushover

Down alerts go at high priority, which sounds through quiet hours. Recovery, slow and the rest go at normal priority. With "Repeat until acknowledged", the alert that a monitor went down goes at emergency priority: Pushover repeats it every minute for up to three hours until someone acknowledges it, and the recovery stops the repeats. Still-down notices stay at high priority.

1. At pushover.net/apps/build, create an application and copy its API token.
2. Copy your user key from the top of pushover.net, or a group key to reach several people.
3. In StatOSS, under Account, Alerts, choose Pushover, paste the token and the key, tick "Repeat until acknowledged" if you want it, and add it. Press "Send a test".

The delivery record

Every send is on the record under Settings, Alerts: when, what, to which destination, and whether it got through. A send the other side refused (a 4xx from a webhook, a mailbox that does not exist) is marked failed with the answer, and the destination it concerns says so until the next send gets through. A send that did not get through at all (a timeout, a 5xx, a mail server that was down) is tried again after one minute, five and fifteen, and marked failed after that. An email then says what the receiving mail server did with it: delivered, delayed, bounced with the server's answer, or marked as spam. A subscriber whose address bounced for good, or who marked the mail as spam, is removed. Subscriber messages are on the same record, on the Subscribers tab. Rows are kept for 30 days.

The webhook

Every alert is one JSON POST with the fields event (went-down, down-changed, still-down, recovered, went-slow or back-to-normal), page, monitor, url, pageUrl, error, downSince, latencyMs, thresholdMs, regions (while down, the regions it is down from), everywhere (whether that is every region) and at (milliseconds since the epoch). down-changed says the outage spread to other regions or left some. The body is signed with HMAC-SHA256 using the secret shown on the settings page, sent as X-StatOSS-Signature: sha256=<hex>, and the event name is repeated in X-StatOSS-Event. Answer with any 2xx. The monitor's name also goes out as checkpoint, the field's name before 14 September 2026.

{
  "event": "went-down",
  "page": "Northwind",
  "monitor": "API",
  "url": "https://api.northwind.example/health",
  "pageUrl": "https://northwind.statoss.com",
  "error": "timeout",
  "downSince": null,
  "latencyMs": 10000,
  "thresholdMs": null,
  "regions": ["North America"],
  "everywhere": false,
  "at": 1789456789000
}