Skip to main content

OnCall user guide

Updated

Overview

OnCall is the scheduling and incident-response product for responder teams. It tracks who is on call right now, rotates coverage automatically, routes incoming alerts to the right person, escalates when alerts aren't acknowledged, and manages incidents through their full lifecycle (triggered, acknowledged, resolved). It's the replacement for tools like PagerDuty.

Alerts can come in from Grafana, Prometheus, Datadog, PagerDuty-compatible senders, or any custom source via a generic webhook. OnCall normalizes them, dedupes duplicates, and fires off phone, push, and voice pages based on your escalation policies.

Key Features

  • Schedules and rotations — Layered schedules with daily, weekly, or custom rotation patterns. Per-schedule timezone. Start and end dates.
  • Escalation policies — Ordered steps with per-step delays. Each step targets a user or team.
  • Services — Named services with criticality, alert grouping, auto-resolve timers, and a default escalation policy.
  • Alert ingest — Public webhook per alert source. Built-in adapters for Grafana, Prometheus (Alertmanager), Datadog, PagerDuty-style payloads, and a generic shape. Fingerprint-based deduplication stops alert storms.
  • Incidents — Full lifecycle (triggered → acknowledged → resolved). Timeline, notes, war rooms, conference bridges, playbook executions.
  • Overrides — Swap coverage for a specific time window without rebuilding the schedule.
  • Shift marketplace — Offer your shift to the team, let someone claim it, admin approves the swap.
  • Mobile push notifications — Expo-based push for acknowledging pages on the go.
  • Phone paging — Integrated with Voice for phone-call escalation (voice reads the incident details).
  • Post-incident reviews (PIRs) — Root cause, timeline, MTTD, action items, follow-up tasks.
  • Stakeholder comms — Drafted messages for customers, leadership, or other audiences during an incident.
  • Fatigue Manager (/oncall/fatigue) — Per-user fatigue score based on recent page load; dismiss to acknowledge. Reports are at /oncall/reports and Analytics at /oncall/analytics.
  • Time tracking — Log time against incidents, mark billable, sync approved entries to PSA.
  • Compensation — On-call and incident compensation reports.
  • iCal feed — Subscribe to your on-call calendar from Google Calendar, Outlook, Apple Calendar.
  • Skills — Tag users with skills so skills-aware routing can pick the right responder.

How To: Set Up Your First Schedule

  1. Go to OnCall and open the Setup Wizard, which walks through schedule, service, and escalation policy creation.
  2. Go to Schedules and click Create Schedule.
  3. Name the schedule, pick a timezone, and optionally link a team.
  4. Add a layer. Pick rotation type (daily, weekly, or custom) and pick the users in rotation order. Custom rotations let you set a specific rotation length in hours or days.
  5. Optionally add a second layer for secondary on-call coverage or for a different rotation cadence.
  6. Save. The schedule starts rotating immediately. View who's on call now under On-Call Now on the dashboard.

How To: Create an Escalation Policy

  1. Go to Escalation Policies and click Create.
  2. Add steps in order. For each step set:
    • Delay — how many minutes to wait before this step (step 0 fires immediately).
    • Targets — one or more users or teams. Teams page every member in the team.
    • Notify methods — phone, push, or both.
  3. Set Repeat times if you want the policy to loop through all steps again when the final step has no acknowledgement.
  4. Save. The policy can now be attached to services or alert sources.

How To: Route Alerts from Grafana, Prometheus, or Datadog

  1. Go to Alert Sources and click Create.
  2. Name the source (e.g., "Prod Grafana"), pick the adapter type (grafana, prometheus, datadog, pagerduty, or generic), and select the escalation policy.
  3. Save. Copy the generated integration URL — it looks like https://api.theonestack.com/api/v1/oncall/alerts/ingest/{integration_key}.
  4. In Grafana (or your monitoring tool), add a new webhook contact point pointing at the integration URL. No auth header is needed — the key is part of the URL.
  5. Test by triggering a test alert. OnCall will create an incident, fire the escalation policy's first step, and show the incident in the dashboard.

The generic adapter accepts {title, description, severity, fingerprint} and is useful for custom scripts.

How To: Configure a Service

  1. Go to Services and click Create.
  2. Set the name, description, and criticality.
  3. Pick a default escalation policy — this is what fires when an alert hits the service without its own routing.
  4. Choose an alert grouping strategy:
    • Intelligent — groups similar alerts automatically.
    • Time-window — groups alerts within a fixed window of minutes.
    • Off — every alert is its own incident.
  5. Set Auto-resolve hours — acknowledged incidents without further action will auto-resolve after this window (default 4 hours).
  6. Optionally link a schedule and team.
  7. Save.

How To: Acknowledge or Resolve an Incident

  1. When you're paged, open the push notification or the incident link.
  2. Click Acknowledge to stop the escalation from walking to the next step. Your username is recorded on the incident and the timeline.
  3. Work the incident — add notes, link a conference bridge, launch a playbook.
  4. Click Resolve when done. Add a brief resolution note.

If an incident is acknowledged but not resolved, it will auto-resolve after the service's auto-resolve hours unless you touch it again (which resets the clock).

How To: Add a One-Time Override

  1. Go to Schedules and open the schedule.
  2. Click Add Override.
  3. Pick the user taking the shift, set start and end times, add a reason.
  4. Save. The override replaces the rotation for that window only. The original rotation resumes after.

Use this for PTO, swapping a single shift, or covering an unexpected absence.

How To: Use the Shift Marketplace

  1. Open the schedule and click on your shift.
  2. Click Offer Shift — choose whether to offer to the whole team or request specific coverage.
  3. Teammates see offers under Shift Marketplace. They can claim an offer.
  4. An admin approves or rejects the swap.
  5. Once approved, the shift is swapped via an override.

How To: Run an Incident War Room

  1. Open an active incident. Click Open War Room.
  2. Click Join — this adds you to the participant list.
  3. Use Post Update to share status; each update is recorded as a note on the incident timeline.
  4. Click Generate AI Brief to produce a short summary of the incident to brief new joiners.
  5. Click Create Conference Bridge to spin up a voice bridge (Zoom/Teams/Meet) attached to the incident.

How To: Create a Post-Incident Review

  1. Open a resolved incident. Click Create Post-Incident Review.
  2. Fill in:
    • Root cause — what actually caused it.
    • Contributing factors — things that made it worse or slower to detect.
    • Timeline of events — ordered list of what happened when.
    • What went well / what went wrong — honest retrospective.
    • Action items and follow-up tasks — with owners.
  3. Save as draft. Edit as needed.
  4. Click Publish when complete. Published PIRs are read-only and discoverable.

How To: Enable Mobile Push

  1. Install the OnCall mobile app and sign in.
  2. Grant the app notification permissions on first launch. The app registers its push token with OnCall automatically.
  3. Go to Notifications in the web app to view and update your preferences (which channels should page you for which severities).
  4. Use Send Test Push from Push Tokens to verify delivery.

How To: Log Time on an Incident

  1. Open a resolved incident.
  2. Click Log Time. Enter start and end time (or duration) and notes. Mark as billable if applicable.
  3. Go to Time Tracking to see your entries.
  4. Admins approve entries under Bulk Approve.
  5. Click Sync to PSA to push approved entries to the PSA product as billable time entries.

How To: Subscribe to Your On-Call Calendar (iCal)

  1. Go to Calendar.
  2. Click Generate iCal Feed. Copy the URL.
  3. In Google Calendar, Outlook, or Apple Calendar, add a new calendar subscription using the URL. Your on-call shifts will appear alongside your other calendars.
  4. If the URL is ever shared outside trusted people, click Regenerate Token — the old URL stops working.

Frequently Asked Questions

What happens if nobody acknowledges an alert? The escalation engine advances to the next step after the step's delay expires, paging the next target. If the final step is reached without acknowledgement, an escalation.exhausted event is emitted — the incident stays open awaiting manual response.

How does deduplication work? Alerts carry a fingerprint. If an incident with the same fingerprint is still open (not resolved), new alerts with that fingerprint are merged into the existing incident instead of creating duplicates. This is why Grafana / Prometheus alerts during an outage don't spam you.

Can the same person be on two schedules at once? Yes. They'll appear as on-call on both. Alerts routed to either schedule will page them.

What's the difference between an override and a swap in the shift marketplace? A shift marketplace swap still requires admin approval and formalizes the trade through the marketplace flow. An override is a direct admin or user action for a specific window (PTO, last-minute cover). Both write rows into the same overrides table.

How are SLAs tracked? Go to Settings > Incident SLA and set a resolve-within-minutes value (or hours). Every 5 minutes OnCall checks open incidents; any that exceed the SLA are marked breached and an sla_breach event is emitted. Analytics shows breach rates by service and severity.

What's the difference between "triggered" and "acknowledged"? Triggered means the incident fired but no human has claimed it yet — escalations continue. Acknowledged means someone is actively working on it — escalations stop. Resolved means the incident is closed.

Can I silence a noisy alert source temporarily? Deactivate the alert source under Alert Sources. Inbound alerts on that integration key will be rejected (410 Gone) until you reactivate it.

What if an alert source's URL leaks? The URL carries the integration key. Delete the alert source (creates a new key) and reconfigure the sender. OnCall also throttles failed-lookup attempts per URL prefix to prevent scanning.

Does OnCall call my phone? Yes, when a step's notify method includes phone paging. OnCall bridges to Voice, which places an outbound call and reads the incident title and severity via text-to-speech.

How do fatigue scores work? OnCall computes a score per user based on recent pages (density, time of day, weekends). High scores show a warning in the dashboard so you can spread load. You can dismiss a warning to acknowledge it.

Troubleshooting

I'm not getting paged for alerts. Confirm you're on call: check On-Call Now. Check the escalation policy attached to the service or alert source — is your user (or your team) a step target? Check your notification preferences — phone/push enabled? If you're on the mobile app, make sure notification permissions are granted and the device has internet.

Alerts are arriving but no incident is created. Check that the alert source is active (not deactivated). Check the request body matches the adapter type — Grafana adapter expects Grafana-shaped payloads. Use the Webhook Templates endpoint to see sample payloads. If duplicates are being ingested, the first one creates the incident and subsequent ones dedupe against its fingerprint.

Incident auto-resolved too early. Raise the service's Auto-resolve hours. Default is 4 hours — for slow-burn incidents you can set it to 24 or 48.

My rotation is on the wrong user. Rotations are deterministic from the layer's start date and rotation length. Check the layer's timezone — if it's wrong, the rotation may be off by hours. Verify the users array order; rotation goes through them in the listed order.

An override didn't take effect. Check the override's start and end times (UTC vs. local tz can be confusing). Soft-deleted overrides don't apply — check that it's active under Overrides.

Push notifications aren't reaching my phone. Re-register the device: uninstall and reinstall the OnCall mobile app. Send a test push from Push Tokens. Check do-not-disturb settings on the device — OnCall delivers at high priority but system-level DND may still silence them.

Time entries aren't syncing to PSA. Check PSA Sync Status for error details. Common issues: PSA token expired, project/ticket ID mismatch, or the entry not marked billable. Fix the issue and retry with Sync to PSA.

I can't see a teammate's schedule. Schedules are visible to all users in the organization. If a schedule seems missing, it may be soft-deleted — ask an admin to check the archived schedules list.

I keep missing pages on my phone (but push works). Check your registered phone number under Notification Preferences. Confirm your carrier isn't blocking the outbound caller ID (Voice's platform number). Add the Voice caller ID to your contacts to avoid spam filtering.