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

# Set up on-call and notifications

> Make sure every page reaches a person who can act: verified notification methods, schedules without gaps, a default escalation policy, fallback routes, and a rehearsal.

A rule that fires at 3 a.m. is only as good as the path to a person who can act. Most missed pages come
from the path, not the rule: an unverified phone number, a schedule with a gap on Sundays, an escalation
policy that nobody created. Build the path once, then prove it with a rehearsal.

## Decide who answers what

Before configuring anything, write down for each service: the team that owns it, who is on call first,
who comes next, and which severities justify a phone call at night.

| Severity | Typical response | Typical channel |
| - | - | - |
| **Critical** | Wake someone up now. | IM at once, then SMS, then a phone call. |
| **Error** | Act within working hours, or soon. | IM, then SMS. |
| **Warning** | Look during the day. | IM or email only. |
| **Info** | No page. | A dashboard or a report. |

Group the people of each owning team in a [team](https://docs.molesignal.com/en-US/identity/teams.md#teams); schedules, escalation
targets, and fallback routes all refer to teams.

## Give every person a verified way to be reached

1. An administrator configures the connectors under
   [Settings → Notify → Connectors](https://docs.molesignal.com/en-US/notification-channels#create-and-test-a-connector): an IM app,
   email, and phone and SMS for critical pages. **Send test** on each one.
2. Each member binds personal methods under [Account settings → Notify](https://docs.molesignal.com/en-US/account.md#notify) and sends a
   test to each.
3. An administrator with `org.members.manage` **Verifies** each method after confirming that it belongs to
   the person. Unverified methods never deliver.
4. Each member orders the methods for **Alert events**, with waits that escalate the channel: for example
   IM at once, SMS after 3 minutes, a phone call after 5 minutes. Later steps stop as soon as someone
   acknowledges.

Quiet hours stop notifications for a person, and they are not sent later. Turn on **Allow critical alerts
to bypass quiet hours** for everyone on a schedule that receives critical pages.

## Build schedules without gaps

Create one [on-call schedule](https://docs.molesignal.com/en-US/alerting/on-call.md#create-a-schedule) per team, in the timezone of the
team:

* a **Weekly** rotation with a handoff in working hours, when both people are awake;
* for follow-the-sun or business-hours coverage, a first rotation restricted to working hours and a
  second rotation below it for the remaining hours;
* every member, in the order of the rotation, and at least two people per schedule.

Check **Next 7 days** before saving, and look for **Coverage gap** in the schedule list and on
[Home](https://docs.molesignal.com/en-US/home.md#on-call-activity-and-dashboards). Record leave and swaps as
[temporary overrides](https://docs.molesignal.com/en-US/alerting/on-call.md#temporary-coverage) ahead of time, and **Export calendar** so
the shifts appear in the calendar of each person.

## Create the default escalation policy first

Rules saved in the rule workbench use the policy named `default`; without it, their incidents page nobody.
See [The default policy](https://docs.molesignal.com/en-US/alerting/on-call.md#the-default-policy).

| Step | Targets | Ack timeout | Applies from |
| - | - | - | - |
| 1 | The primary schedule of the team. | 5 minutes | Any severity |
| 2 | The secondary schedule, or the team lead. | 10 minutes | **Error** |
| 3 | The whole team. | 15 minutes | **Critical** |

Turn on **Repeat the whole policy until acknowledged** with a small **Max loops** for critical services.
Create further policies for teams with different needs, and point rules at them through the API with
`escalation_policy_id`.

## Add safety nets

* [Fallback routes](https://docs.molesignal.com/en-US/notification-channels#configure-fallback-routes) deliver to a team channel or an
  organization address when no personal method of a recipient works.
* [Notify policies](https://docs.molesignal.com/en-US/notification-channels#create-templates-and-policies) decide the template and the
  connectors of each event; the live preview shows who would receive an event without sending it.
* The [Delivery log](https://docs.molesignal.com/en-US/notification-channels#inspect-and-retry-deliveries) shows every attempt, so a
  failing connector is found before an incident needs it.

## Rehearse

Run a drill in working hours, and repeat it after every larger change:

1. Fire a test rule on purpose with [Trigger a rule](https://docs.molesignal.com/en-US/api/alerting/trigger-rule.md).
2. Check that the person on call receives the page on each channel, in the expected order.
3. Wait without acknowledging, and check that the escalation reaches step 2.
4. Acknowledge, and check that later steps and channels stop.
5. Resolve, and review the **Delivery log** for failures.

## Acceptance criteria

* Every person on a schedule has at least two verified methods, one of them by phone for critical pages.
* No schedule shows a coverage gap in the next 7 days.
* A policy named `default` exists, and each step has a person or a schedule.
* Fallback routes exist for every team that receives pages.
* The last drill reached the person on call, escalated as expected, and stopped on acknowledgement.

## Related guides

* [On-call and escalation](https://docs.molesignal.com/en-US/alerting/on-call.md)
* [Notification channels and delivery](https://docs.molesignal.com/en-US/notification-channels)
* [Account settings](https://docs.molesignal.com/en-US/account.md)
* [Make production alerts actionable](https://docs.molesignal.com/en-US/best-practices/actionable-alerts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.