On-Call Schedules
Set up on-call rotations so the right person is always available to respond to incidents.
On-call schedules define who is responsible for responding to incidents at any given time. When an escalation policy targets an on-call schedule, Ionhour automatically resolves the current on-call person and notifies them.
How On-Call Schedules Work
A schedule is workspace-scoped and contains one or more rotations. Each rotation defines a repeating cycle of participants who take turns being on-call. When an incident fires, Ionhour determines who is currently on-call by evaluating the rotation's type, handoff time, and participant order.
Schedules also support overrides — temporary one-off assignments that take precedence over the regular rotation (e.g., covering for a teammate on vacation).
Schedule Settings
| Setting | Required | Description |
|---|---|---|
| Name | Yes | Human-readable label for the schedule |
| Timezone | Yes | The timezone used for handoff times and override windows. Default: UTC. |
| Description | No | Optional description of the schedule's purpose |
| Handoff notification (minutes) | No | How many minutes before a handoff to notify the incoming on-call person. Default: 15. Set to null to disable. |
| Enabled | No | Whether the schedule is active. Default: true. |
Always set the timezone to match your team's working timezone. Handoff times and override windows are interpreted in this timezone.
Rotations
A rotation defines the repeating pattern of on-call shifts. Each schedule can have multiple rotations, layered by position (lower position = higher priority).
Rotation Settings
| Setting | Required | Description |
|---|---|---|
| Type | Yes | Rotation type: daily, weekly, or custom |
| Effective from | Yes | When this rotation starts |
| Effective until | No | When this rotation ends. null means indefinite. |
| Handoff time | Yes | Time of day when shifts change (e.g., 09:00). Interpreted in the schedule's timezone. |
| Handoff day | No | Day of week for weekly rotations (1 = Monday, 7 = Sunday). Default: 1 (Monday). |
| Custom shift hours | No | Shift length in hours for custom rotations (e.g., 12 for 12-hour shifts). |
| Restrictions | No | Optional time-of-day or day-of-week restrictions for when the rotation is active. |
| Layer position | Yes | Priority within the schedule. Lower position = higher priority. |
Rotation Types
| Type | Shift length | Handoff |
|---|---|---|
| Daily | 24 hours | Every day at the configured handoff time |
| Weekly | 7 days | Every week on the configured handoff day at the handoff time |
| Custom | Configurable | Every N hours from the effective start time |
Participants
Each rotation has an ordered list of participants — the people who cycle through on-call duty. Participants rotate in position order: participant 1 takes the first shift, participant 2 takes the next, and so on. After the last participant, the cycle repeats from the beginning.
| Setting | Description |
|---|---|
| User | The workspace member assigned to this position |
| Position | Order in the rotation (0-indexed). Must be unique within the rotation. |
Multiple Rotation Layers
You can create multiple rotations within a single schedule. Layers are evaluated by position — a rotation with layerPosition: 0 takes priority over layerPosition: 1. This is useful for:
- Business hours vs. after hours — A daily rotation for business hours (9am-6pm) at layer 0, and a weekly rotation for nights/weekends at layer 1.
- Temporary coverage — A time-limited rotation at layer 0 that overrides the regular rotation for a specific period.
Overrides
Overrides provide a way to temporarily replace the scheduled on-call person without modifying the rotation itself. Common use cases include vacation coverage, shift swaps, and emergency reassignment.
Override Settings
| Setting | Required | Description |
|---|---|---|
| Override user | Yes | The person who will be on-call during the override window |
| Start at | Yes | When the override begins |
| End at | Yes | When the override ends |
| Replaced user | No | The person being replaced. If null, the override applies regardless of who is normally on-call. |
| Reason | No | Optional note explaining why the override was created |
Override Behavior
- Overrides always take priority over the regular rotation.
- Multiple overlapping overrides are resolved by most-recently-created first.
- When an override specifies a
replacedUser, it only activates during shifts where that specific user would normally be on-call. IfreplacedUserisnull, the override applies unconditionally. - Overrides are automatically inactive outside their start/end window — no cleanup needed.
Example: Vacation Coverage
Alice is on-call next week (Mon 9am to Mon 9am), but she'll be on vacation. Bob agrees to cover:
| Setting | Value |
|---|---|
| Override user | Bob |
| Start at | Monday 09:00 |
| End at | Next Monday 09:00 |
| Replaced user | Alice |
| Reason | Alice on vacation |
During this window, any escalation targeting this schedule will notify Bob instead of Alice.
Using Schedules in Escalation Policies
On-call schedules are most powerful when used as escalation step targets. When an escalation step targets a schedule:
- Ionhour evaluates the schedule's rotations and overrides to determine who is currently on-call.
- The on-call person is notified through their configured contact methods.
- If no one is on-call (e.g., all rotations are outside their effective dates), the step is skipped and logged.
This is the recommended approach for incident routing — instead of hardcoding a specific user in your escalation policy, point to a schedule. The right person is always notified, even during handoffs and vacations.
Handoff Notifications
When handoffNotificationMinutes is configured (default: 15 minutes), Ionhour sends a notification to the incoming on-call person before their shift starts. This gives them time to prepare — check their phone is charged, silence non-urgent notifications, review any ongoing incidents.
Set this to null to disable handoff notifications entirely.
Best Practices
- Use weekly rotations for most teams. Daily rotations cause context-switching fatigue. Weekly rotations give each person enough time to settle in and handle follow-ups.
- Set handoff time to a working hour. Don't hand off at midnight — hand off at 9am or 10am so the incoming person can review the state of things during business hours.
- Create overrides proactively. As soon as someone knows they'll be unavailable, create the override. Don't wait until the day of.
- Use overrides, not rotation edits. Modifying a rotation's participant list affects future shift calculations. For temporary changes, always use overrides.
- Set the timezone correctly. A schedule in
America/New_Yorkwith a 9am handoff will hand off at 9am Eastern, regardless of the server's timezone. If your team spans timezones, pick the timezone of the team lead or the majority. - Combine with escalation policies. A schedule alone doesn't send notifications — it just defines who is on-call. Connect it to an escalation policy to actually route incidents.