Pingward Docs

Appearance

On-Call Schedules ​

On-Call Schedules define which team member is responsible for responding to issues at any given time. They integrate with escalation policies to ensure that when an issue escalates, the right person is notified immediately based on a rotating schedule.

Overview ​

In Pingward's alerting pipeline, on-call schedules answer the question: "Who should be notified right now?"

Issue Escalation Started → Escalation Policy → Tier 1 Target: On-Call Schedule → Resolve Current On-Call User → Notify That User

An on-call schedule consists of:

  • A rotation that cycles through team members on a daily or weekly basis
  • A timezone that governs when handoffs occur
  • A handoff time (and optionally day) when duty transfers to the next person
  • A list of participants in rotation order
  • Optional overrides for temporary changes (vacations, swaps)

Without on-call schedules, escalation policies would need to target specific users directly, which doesn't scale and doesn't account for time-based rotation.

Creating a Schedule ​

Via Dashboard ​

  1. Navigate to On-Call Schedules in the sidebar
  2. Click + New Schedule
  3. Fill in the form:

Basic Information:

Schedule Name: Primary On-Call
Timezone: America/New_York
Description: Main engineering on-call rotation (optional)

Rotation Configuration:

Rotation Type: Weekly
Handoff Time: 09:00
Handoff Day: Monday (for weekly rotations)

Participants:

#1: Alice Chen
#2: Bob Martinez
#3: Carol Kim
#4: David Park
  1. Click Create Schedule

Via API ​

http
POST /api/on-call-schedules
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "name": "Primary On-Call",
  "description": "Main engineering on-call rotation",
  "timezone": "America/New_York",
  "rotationConfig": {
    "type": "weekly",
    "handoffTime": "09:00",
    "handoffDay": "Monday",
    "participants": [
      { "userId": "user-id-1", "order": 0 },
      { "userId": "user-id-2", "order": 1 },
      { "userId": "user-id-3", "order": 2 }
    ]
  }
}

Configuration ​

Rotation Types ​

Weekly ​

One person is on-call for an entire week before handing off to the next person in the rotation.

Configuration:

Rotation Type: Weekly
Handoff Time: 09:00
Handoff Day: Monday

Effective schedule (4 participants):

Week 1: Alice (Mon 09:00 → next Mon 09:00)
Week 2: Bob (Mon 09:00 → next Mon 09:00)
Week 3: Carol (Mon 09:00 → next Mon 09:00)
Week 4: David (Mon 09:00 → next Mon 09:00)
Week 5: Alice (cycle repeats)

Use when:

  • Team is comfortable with week-long on-call shifts
  • You want fewer handoffs (less coordination overhead)
  • Team has 3+ members so each person gets adequate time off

Daily ​

On-call duty rotates every day at the specified handoff time.

Configuration:

Rotation Type: Daily
Handoff Time: 09:00

Effective schedule (3 participants):

Day 1: Alice (09:00 → next day 09:00)
Day 2: Bob (09:00 → next day 09:00)
Day 3: Carol (09:00 → next day 09:00)
Day 4: Alice (cycle repeats)

Use when:

  • Shorter shifts are preferred to reduce fatigue
  • Team is small and wants to distribute load evenly
  • High-volume alerting makes week-long shifts burdensome

Handoff Time ​

The time of day (in the schedule's timezone) when on-call duty transfers from one person to the next.

Common choices:

  • 09:00 -- Handoff at start of business day. Outgoing person can brief incoming person during overlap.
  • 17:00 -- Handoff at end of business day. Fresh person takes over for evening/night.
  • 00:00 -- Midnight handoff. Clean calendar-day boundaries.

Recommendation: Choose a time during business hours so both the outgoing and incoming on-call engineers are available for a smooth transition.

Handoff Day ​

For weekly rotations only. The day of the week when the rotation advances to the next person.

Common choices:

  • Monday -- Standard work-week alignment. Most teams use this.
  • Wednesday -- Mid-week handoff splits weekend duty between two people.
  • Friday -- Weekend on-call starts fresh on Friday.

Recommendation: Monday is the most common choice. It aligns with the start of the work week and gives the incoming person a full business day to get oriented before the weekend.

Participants ​

Team members who rotate through on-call duty. The rotation follows the order shown in the participant list.

Adding participants:

  1. In the schedule creation form, use the "Add participant" dropdown
  2. Select a team member
  3. They are added to the end of the rotation order

Rotation order:

  • Person #1 goes first
  • Person #2 goes next
  • After the last person, it cycles back to #1

Removing participants:

  • Click Remove next to a participant's name
  • Remaining participants are automatically re-ordered

Minimum: At least one participant is required. In practice, you should have at least 2 participants for a meaningful rotation.

Current On-Call ​

From the Schedule List ​

The on-call schedule list page shows who is currently on-call for each schedule. The current on-call user is displayed with an "On-Call" badge next to the schedule name.

From the Schedule Detail ​

The schedule detail page shows the currently on-call person in the "Schedule Info" panel under Currently On-Call, highlighted with an active status badge.

Via API ​

http
GET /api/on-call-schedules/{id}/current
Authorization: Bearer <your-jwt-token>

Returns:

json
{
  "userId": "user-id-of-current-on-call",
  "scheduleId": "schedule-id",
  "timestamp": "2024-01-15T14:30:00Z"
}

Timeline ​

The schedule detail page includes a Timeline (Next 14 Days) view that shows who will be on-call for the upcoming two weeks. Each entry shows:

  • User -- The on-call person
  • Start -- When their shift begins
  • End -- When their shift ends
  • Type -- "Scheduled" (regular rotation) or "Override" (temporary change)

This timeline accounts for both the regular rotation and any active overrides, giving you a complete picture of upcoming on-call coverage.

Via API ​

http
GET /api/on-call-schedules/{id}/timeline
Authorization: Bearer <your-jwt-token>

Query parameters:
  ?from=2024-01-15T00:00:00Z   (default: now)
  ?to=2024-01-29T00:00:00Z     (default: from + 14 days)

Overrides ​

Overrides are temporary changes to the on-call schedule. They allow a different team member to take over on-call duty for a specific time window, without permanently changing the rotation.

During an override period, the override user replaces whoever would normally be on-call. When the override ends, the regular rotation resumes automatically.

Creating an Override ​

From the schedule detail page:

  1. Navigate to the on-call schedule
  2. Click + Add Override
  3. Fill in the form:
Override User: The person taking over on-call duty
Start Time: When the override begins
End Time: When the override ends
Reason: Why this override was created (optional)
  1. Click Create Override

Via API:

http
POST /api/on-call-schedules/{id}/overrides
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "overrideUserId": "user-id-of-replacement",
  "startTime": "2024-01-20T09:00:00Z",
  "endTime": "2024-01-22T09:00:00Z",
  "reason": "Alice on vacation, Bob covering"
}

Viewing Active Overrides ​

The schedule detail page shows all active overrides in the Active Overrides panel, including:

  • Override user name
  • Start and end times
  • Reason (if provided)
  • Delete button to remove the override

Deleting an Override ​

If plans change, you can delete an override before or during its active period:

  1. Open the schedule detail page
  2. Find the override in the Active Overrides table
  3. Click Delete and confirm

The regular rotation resumes immediately for the affected time window.

Use Cases ​

Vacation Coverage ​

Scenario: Alice is on-call next week but going on vacation
Override User: Bob
Start: Monday 09:00
End: Following Monday 09:00
Reason: Alice on vacation

Bob covers Alice's entire shift. When the override ends, the rotation continues normally -- Carol takes over the following week as originally scheduled.

On-Call Swap ​

Scenario: Bob has a dentist appointment Tuesday afternoon
Override User: Carol
Start: Tuesday 13:00
End: Tuesday 18:00
Reason: Bob/Carol swap for Tuesday afternoon

Carol covers just the afternoon. Bob remains on-call before and after the override window.

Emergency Coverage ​

Scenario: Current on-call engineer is unreachable during an incident
Override User: Engineering Manager
Start: Now
End: Tomorrow 09:00
Reason: Emergency coverage - on-call unreachable

Immediate coverage while the situation is resolved.

Conference or Training ​

Scenario: Two team members attending a conference
Override User: Remaining team member
Start: Wednesday 00:00
End: Friday 23:59
Reason: Team at re:Invent conference

Ensures coverage during multi-day events when multiple rotation members are unavailable.

Integration with Escalation Policies ​

On-call schedules are used as targets in escalation policy tiers. When an escalation tier fires, Pingward resolves the current on-call user from the schedule and sends them a notification.

How It Works ​

Escalation Policy: "Payment Team Escalation"
├── Tier 1 (0 min): On-Call Schedule "Primary On-Call" → Resolve → Alice (currently on-call)
├── Tier 2 (5 min): On-Call Schedule "Secondary On-Call" → Resolve → Manager on-call
└── Tier 3 (15 min): Integration "Engineering Slack Channel"

When an issue triggers this policy:

  1. Tier 1: Pingward looks up "Primary On-Call" schedule, finds Alice is on-call, notifies her
  2. 5 minutes, no acknowledgement: Pingward looks up "Secondary On-Call" schedule, notifies the manager
  3. 15 minutes, no acknowledgement: Pingward sends to the Slack channel

Multiple Schedules ​

You can create multiple on-call schedules for different purposes:

"Primary On-Call" -- Main engineering rotation (24/7)
"Secondary On-Call" -- Engineering managers (backup)
"Database On-Call" -- DBA rotation (database-specific issues)
"Weekend On-Call" -- Weekend-only coverage with different participants

Each schedule can be used as a target in different escalation policy tiers, allowing layered notification strategies.

Best Practices ​

Schedule Design ​

Match shift length to team size:

  • 2-3 people: Daily rotation (weekly shifts are too long)
  • 4-6 people: Weekly rotation (standard)
  • 7+ people: Weekly rotation with secondary/backup schedule

Keep rotations simple:

  • Use a single rotation type per schedule
  • Avoid frequent changes to participant order
  • Let overrides handle exceptions rather than modifying the base rotation

Overlap and Coverage ​

Ensure 24/7 coverage: If your service requires around-the-clock monitoring, make sure every hour is covered. A single schedule with a daily or weekly rotation handles this automatically -- there are no gaps between shifts.

Use business-hours handoffs: Schedule handoffs during business hours so both engineers are available for a transition. This allows the outgoing person to brief the incoming person on any active issues.

Plan for overlap: Consider having a brief overlap period where both the outgoing and incoming on-call engineers are available. A 09:00 handoff naturally provides this during the workday.

Timezone Considerations ​

Choose the right timezone:

  • If your team is in one timezone, use that timezone
  • If your team spans multiple timezones, use UTC or the timezone of the majority
  • The handoff time is interpreted in the schedule's timezone

Example for a distributed team:

Schedule Timezone: UTC
Handoff Time: 14:00 UTC

Effective handoff times:
- New York: 09:00 AM EST
- London: 14:00 GMT
- Tokyo: 23:00 JST

Supported timezones include major cities across all regions: UTC, Americas (New York, Chicago, Denver, Los Angeles, Toronto, Vancouver, Sao Paulo, Buenos Aires), Europe (London, Paris, Berlin, Amsterdam, Stockholm, Helsinki, Moscow), Asia (Dubai, Kolkata, Singapore, Shanghai, Tokyo, Seoul), and Oceania (Sydney, Melbourne, Auckland).

Override Hygiene ​

  • Always include a reason: Helps the team understand why coverage changed
  • Clean up expired overrides: Delete overrides that are no longer needed
  • Plan ahead: Create overrides for known absences (vacations, conferences) as early as possible
  • Communicate: Let the team know when overrides are in place, especially for unplanned changes

Participant Management ​

  • Keep the rotation current: Remove people who leave the team promptly
  • Onboard gradually: New team members should shadow on-call before being added to the rotation
  • Balance the load: Ensure the rotation is fair -- everyone should take roughly equal shifts over time

Troubleshooting ​

Nobody On-Call ​

Symptoms: Schedule shows "No one" as currently on-call.

Possible causes:

  1. No participants added to the rotation
  2. Rotation configuration is empty or invalid

Resolution:

  1. Open the schedule and check the participant list
  2. Add at least one participant to the rotation
  3. Verify the rotation config (type, handoff time, handoff day)

Wrong Person On-Call ​

Symptoms: The wrong team member is shown as on-call.

Possible causes:

  1. Active override replacing the scheduled person
  2. Participant order changed recently
  3. Timezone mismatch (handoff hasn't occurred yet in the schedule's timezone)

Resolution:

  1. Check for active overrides in the schedule detail page
  2. Verify the participant order matches your expectations
  3. Check the schedule's timezone vs. the current time
  4. Review the 14-day timeline to see when the next handoff occurs

Notifications Going to Wrong Person ​

Symptoms: Issue notifications sent to someone not on-call.

Possible causes:

  1. Escalation policy targeting the wrong schedule
  2. Multiple schedules with similar names
  3. Stale cache (may take up to 30 seconds to update)

Resolution:

  1. Check which on-call schedule the escalation policy references
  2. Verify the current on-call user via the schedule detail page or /current API endpoint
  3. Wait 1-2 minutes and check again if recently changed

API Reference ​

List On-Call Schedules ​

http
GET /api/on-call-schedules
Authorization: Bearer <your-jwt-token>

Get Schedule Detail ​

http
GET /api/on-call-schedules/{id}
Authorization: Bearer <your-jwt-token>

Returns full schedule details including rotation config and active overrides.

Create Schedule ​

http
POST /api/on-call-schedules
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "name": "string (required, max 255 chars)",
  "description": "string (optional, max 1000 chars)",
  "timezone": "string (default: UTC, max 100 chars)",
  "rotationConfig": {
    "type": "weekly | daily",
    "handoffTime": "HH:mm (e.g., 09:00)",
    "handoffDay": "Monday | Tuesday | ... | Sunday (weekly only)",
    "participants": [
      { "userId": "string", "order": 0 },
      { "userId": "string", "order": 1 }
    ]
  }
}

Update Schedule ​

http
PUT /api/on-call-schedules/{id}
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "name": "Updated name",
  "timezone": "America/Chicago",
  "rotationConfig": { ... }
}

All fields are optional. Only provided fields are updated.

Delete Schedule ​

http
DELETE /api/on-call-schedules/{id}
Authorization: Bearer <your-jwt-token>

Get Current On-Call ​

http
GET /api/on-call-schedules/{id}/current
Authorization: Bearer <your-jwt-token>

Get Timeline ​

http
GET /api/on-call-schedules/{id}/timeline
Authorization: Bearer <your-jwt-token>

Query parameters:
  ?from=ISO 8601 datetime (default: now)
  ?to=ISO 8601 datetime (default: from + 14 days)

Create Override ​

http
POST /api/on-call-schedules/{id}/overrides
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "overrideUserId": "string (required)",
  "originalUserId": "string (optional)",
  "startTime": "ISO 8601 datetime (required)",
  "endTime": "ISO 8601 datetime (required, must be after startTime)",
  "reason": "string (optional, max 500 chars)"
}

Delete Override ​

http
DELETE /api/on-call-schedules/{scheduleId}/overrides/{overrideId}
Authorization: Bearer <your-jwt-token>

Pingward - API Monitoring Made Simple

Copyright © 2024-present