> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts and notifications

> What Shipways watches for, and who hears about it.

Every five minutes Shipways checks the organization's servers, certificates,
daemons, backups, heartbeats and queue. Anything wrong opens an alert in the
panel; where it goes beyond that is up to you.

## What is watched

| Alert                                 | Opens when                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------- |
| **Server unreachable**                | An agent has not reported for two minutes.                                  |
| **Disk space**, **Memory**, **CPU**   | A reading crosses [the server's threshold](/servers/monitoring#thresholds). |
| **Certificate expiring**              | A certificate is within 14 days of expiry.                                  |
| **Certificate renewal failed**        | A reissue did not go through.                                               |
| **Daemon stopped**                    | Supervisor has given up on a [daemon](/processes/daemons).                  |
| **Deployment failed**                 | A [deployment](/sites/deployments) did not make it.                         |
| **Backup failed**, **Backup overdue** | See [backups](/backups#alerts).                                             |
| **Nothing is running queued work**    | Tasks are queued with nothing to run them.                                  |
| **Heartbeat missed**                  | A [heartbeat](/processes/heartbeats) did not arrive in time.                |

One open alert per subject per type, so a disk that has been full for a week is
one row rather than two thousand notifications.

## Resolving and dismissing

Most conditions clear themselves. A full disk resolves when space is freed; an
unreachable server resolves when its agent reports in.

A deployment that failed happened, and stays happened, so it is acknowledged
rather than resolved.

Dismissing something that is **still true** only hides it until the next check.
A full disk stays full.

## The queue alert

Worth calling out because of what it means about everything else.

Every button in Shipways queues work. With nothing running the queue, they all
appear to do nothing, forever, and the only feedback is a spinner. This alert
is reached by the scheduler rather than by the queue, so it still fires when
the thing it is watching for has happened.

If provisioning, deployments and certificate requests are all sitting at
pending, this is why.

## Where alerts are sent

Owners and admins are always emailed and always see the bell. Beyond that, add
destinations under **Alerts**:

| Type           | What it needs                                                       |
| -------------- | ------------------------------------------------------------------- |
| **Email**      | An address. Nobody needs an account in Shipways to be on this list. |
| **Slack**      | An incoming webhook, from Apps → Incoming WebHooks.                 |
| **Discord**    | A channel webhook, from Edit Channel → Integrations.                |
| **Mattermost** | An incoming webhook, from Integrations.                             |
| **Webhook**    | Anything else. Gets a JSON body describing the alert.               |

The chat services are separate rather than one generic webhook because they do
not agree on what a message looks like — Slack reads `blocks`, Discord reads
`embeds`, Mattermost reads `attachments`. Sending one shape to all three is how
Discord users end up appending `/slack` to their URL.

Each destination chooses which alert types it wants, so "tell me about
certificates but not disk space" is a thing you can actually say.

## Per-site notifications

A site can **replace** the organization's destinations with its own, under its
Settings → Notifications. They replace rather than add to, and leaving them all
empty says nothing about that site at all.

Anything wrong still opens an alert in the panel. This only decides who is told
outside it.