On-call
Schedules with layered rotations and overrides, escalation policies, and pages that tell the right person through the bell, a webhook, Slack, SMS and a phone call, and escalate until someone acknowledges.
On-call in the Incidents sidebar (/incidents/oncall) answers three questions: who is on call now, what is paging
them, and what happens if they do not answer. Everyone in the org can read it. Acknowledging a page and covering a shift
need the write role; schedules, policies and alert sources need an owner or admin.
Schedules
A schedule is a name, a time zone and one or more rotations (layers).
- A rotation is an ordered list of members that take turns. A shift is a number of calendar days (7 by default), handed over at the same local time (9:00 by default) from a start date. Because it counts calendar days and not 24-hour blocks, the handoff stays at 9:00 across a daylight saving change; that week's shift is 167 or 169 hours long. A handoff time that does not exist that day (02:30 on the spring-forward date) happens after the gap, and one that exists twice happens the first time.
- A team's members. Instead of picking people, a rotation can be "members of team X" (an
org team, inherited members included). The turns go in the order people joined the team, and
someone who joins goes to the end of the line; someone who leaves drops out. The schedule follows the team without being
saved again. Agents in the team are left out, since they can't be paged. Over MCP and REST, a rotation takes
team: "<team id>"instead ofmembers. - Layers. The highest layer that covers a moment decides who is on call. A rotation can be restricted to some weekdays and hours (a business-hours layer over a nights-and-weekends one, or a Friday night window that runs past midnight); the layer below covers the rest.
- Overrides put someone on call for a window and beat every layer, for holidays and swaps. The week view shows the result, one bar per person, with overrides outlined.
The page opens with who is on call now for every schedule. Over MCP, incidents_oncall_who says the same, and incidents_oncall_override
covers a shift.
Covering a shift on the calendar
With the write role you can make and move overrides on the week view itself:
- Drag across the week (within a day or over several) to cover that window. When you let go, a dialog asks who covers it; nothing changes until you confirm.
- Drag an override's bar to move it. Moving it to another day keeps its local times: an override from 09:00 to 17:00 on the Friday before a daylight saving change is 09:00 to 17:00 on the Monday after it, even though the elapsed time between the two is an hour more or less. The dialog lets you hand it to someone else as well.
- Tap or click without dragging to open the same dialog: an hour from that spot, or the override you tapped. On a phone this is how it works, since a drag there scrolls the page.
Times snap to the half hour on the schedule's clock (its time zone, not your browser's), and the dialog's From and Until are in that zone too. A 23-hour or 25-hour day is drawn at its real length. A time that the spring-forward change skips lands just after the gap; in the hour that repeats in the autumn, a drag stays in the copy of the hour you pointed at. Escape cancels a drag.
Add override above the list and Move on each row open the same dialog without a pointer, and the line under the week reads out a drag as it happens for screen readers. If the new window overlaps another override, the dialog says so. The overlap is allowed, as it is over the API: while two overrides cover the same moment, the one that starts later wins.
Escalation policies
A policy is a list of levels. Each level names schedules (whoever is on call at that moment), teams and members, and
the minutes to wait before the next level. A team target ({kind: "team", ref: "<team id>"}) pages the team's current
on-call: whoever the schedules with a rotation of that team have on call. When no schedule rotates the team, it pages
everyone in the team, so a team target never pages nobody while the team has people. It can repeat the whole list a number of times, and name a Slack channel. One policy
is the default: it is the one the alert rules and sources use unless they name another.
Pages
A page is created by an alert rule with the action Page the on-call or Open an incident, by an alert source, by hand (Page now), or over REST. It tells level 1 and then:
- The bell. The page is pinned to the top of each told member's bell until it is acknowledged.
- A webhook. The org's webhooks that subscribe to
incidents.pageget one event for level 1 and one for each escalation, with the page, the level and the members told (the event is signed like every org webhook). - SMS and a phone call. A level whose notifications include SMS and Phone call texts each told member's verified number, then calls it a few minutes later unless someone acknowledged. Replying 1 or pressing 1 acknowledges. This goes through Venom Comms and needs a Comms provider. A member without a verified number, including one who came from a team, is skipped, and the incident timeline notes how many were.
- Slack. If the policy names a channel, a message goes there through your org's own Slack app (the same one the error
alerts use). The message has Acknowledge and
Escalate buttons while the page waits for an answer. To make them work, open your Slack app's Interactivity & Shortcuts,
switch it on and paste the Interactivity Request URL from the Slack page in Venom Cloud
(
/api/integrations/slack/<id>/interactivity); a new app made from the page's manifest has it already. The person who clicks must have linked their Slack user with/venom link, and acts with their own role: a viewer is told they cannot. The message is then rewritten with who acknowledged or escalated it; an escalation posts a fresh message for the next level. - The incident timeline, when the page belongs to an incident.
The same alert firing again is the same page (it counts up). Acknowledge stops the escalation; Escalate moves it
to the next level now; Resolve closes it. The sweep cron escalates a page whose delay ran out, once per level, and when
a policy is exhausted the page stays open and stops escalating. Over MCP: incidents_oncall_ack (with resolve: true to close), and incidents_oncall_override_move moves an override.
REST
/incidents/api/v1/oncall/…: now, members, schedules (and schedules/{id}/timeline, schedules/{id}/overrides),
overrides/{id} (PATCH with startAt, endAt and optionally member moves one; DELETE removes it), policies, pages (and pages/{id}/ack|resolve|escalate) and sources. See the contract in
contracts/incidents-openapi.yaml.