Skip to content
Docs
Infrastructure & monitoring

PagerDuty

Let hires see and work incidents in PagerDuty, check who's on call, open an incident when something's really wrong, and be woken when a new one comes in.

Explore 8 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With PagerDuty, a hire can:

  • list incidents (open ones, or resolved too) and read one with its notes and timeline,
  • acknowledge, resolve and reassign incidents, and add notes to them,
  • see who's on call now, level by level,
  • open a new incident on a service, which pages whoever is on call.

Opening an incident pages people

Triggering an incident wakes someone up, so it waits for a person's approval: the hire asks in the thread, and when the approver says yes, Roster opens exactly that incident, once. Hires are also told to check for an open incident first, so nobody is paged twice. To let a hire page without asking, use When it asks first on its Tools tab.

1. Make an API key in PagerDuty

Straight there: PagerDuty's API access keys (sign in if asked), or Integrations → Developer Tools → API Access Keys.

  1. In PagerDuty, open Integrations → API Access Keys and click Create New API Key. Name it Roster.
  2. Tick Read-only API Key if hires should only look, never change incidents.
  3. Copy the key.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for PagerDuty and choose it.
  2. REST API key: paste the key.
  3. Service region: EU if your PagerDuty address ends in .eu.pagerduty.com, otherwise US.
  4. Act as (email): the email of a PagerDuty user. PagerDuty records what hires change (acknowledging, resolving, notes) as this user, so a user named for your team, like oncall-bot@acme.com, reads best. Without it hires can only read.
  5. Click Connect.

To let hires open incidents on a service, that service needs an Events API V2 integration in PagerDuty (the service → Integrations → Add an integration → Events API V2). Roster finds it by itself; you don't paste its key anywhere.

Roster checks the key when you click Connect. Once it's accepted, the connection shows Connected as PagerDuty and its region, and the user hires act as. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on PagerDuty:

  • Read only: list and read incidents, and see who's on call.
  • Read and write: also acknowledge, resolve, reassign, add notes and open incidents.
  • Services: service names or IDs, one per line. The hire only sees incidents of these services, only sees who's on call for them, and only opens incidents on them. Leave it empty for every service the key can see.

Hires refer to incidents by their ID, like PT4KHLK, shown next to the number.

4. Wake hires at once (optional)

With a full-access key, Roster sets this up itself when you connect: it subscribes the connection to new, reopened, escalated and unacknowledged incidents and keeps the signing secret. You only need the steps below with a read-only key, or to change what's sent.

A hire's responsibility can watch PagerDuty: it's woken when a new incident comes in on its services. By default Roster checks PagerDuty every so often. For no delay:

  1. Copy this connection's webhook address from its card in Roster.
  2. In PagerDuty, open Integrations → Generic Webhooks (v3) and click New Webhook. Paste the address, choose the services (or the whole account), and tick at least incident triggered, escalated, reopened and unacknowledged.
  3. Copy the signing secret PagerDuty shows, and paste it in Webhook signing secret on the connection.

Roster checks every delivery's signature and ignores anything that isn't signed with that secret.

If something goes wrong

  • "Didn't accept the connection's credential": the key was deleted, or it's a US key used with the EU region (or the other way round).
  • "Doesn't allow this": the key is read-only and a hire tried to change an incident.
  • "No user to act as": add Act as (email) on the connection.
  • "No Events API v2 integration": add one to that service in PagerDuty (step 2).

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect PagerDuty and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In PagerDuty: Integrations → API Access Keys → Create New API Key (read-only if hires shouldn't change incidents).

When making a key, use these permissions from the connection guide:

  • Full access to acknowledge, resolve and add notes (read-only otherwise)

Connection fields

PagerDuty connection fields
FieldWhat to provide
REST API key
token
Required · sealed secret		In PagerDuty: Integrations → API Access Keys → Create New API Key (read-only if hires shouldn't change incidents).
Service region
region
Optional		EU if your PagerDuty address ends in .eu.pagerduty.com.

Choices: US (us); EU (eu).

Starts with: us.

Act as (email)
fromEmail
Optional		The email of a PagerDuty user: PagerDuty records changes hires make (acknowledge, resolve, notes) as this user. Needed for anything that changes an incident.
Webhook signing secret
webhookSecret
Optional · sealed secret		Optional: from a webhook subscription (Integrations → Generic Webhooks (v3)) sent to this connection's address. New incidents then wake hires at once.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

PagerDuty per-hire limits
FieldWhat to provide
Services
services
Optional		Service names or IDs, one per line. Leave empty for every service the key can see.

Actions

8 actions: 3 only read and 5 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

8 of 8 actions. Open an action for its arguments and full input schema.

list_incidentsRead only

Incidents, newest first: open ones (triggered or acknowledged) unless asked for others.

Approval: Uses your workspace and hire approval settings.

Arguments for list_incidents
ArgumentTypeDetails
statusesOptional"triggered" | "acknowledged" | "resolved"[]See input schema below.Default: ["triggered","acknowledged"]
serviceOptionalstringa service's name or ID
urgencyOptional"high" | "low"See input schema below.
sinceOptionalstringISO time; default the last 30 days
limitOptionalintegerSee input schema below.Default: 25
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "statuses": {
      "default": [
        "triggered",
        "acknowledged"
      ],
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "triggered",
          "acknowledged",
          "resolved"
        ]
      }
    },
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "a service's name or ID"
    },
    "urgency": {
      "type": "string",
      "enum": [
        "high",
        "low"
      ]
    },
    "since": {
      "description": "ISO time; default the last 30 days",
      "type": "string"
    },
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
get_incidentRead only

An incident with its notes and the latest of its timeline (triggered, escalated, acknowledged…).

Approval: Uses your workspace and hire approval settings.

Arguments for get_incident
ArgumentTypeDetails
incidentRequiredstringthe incident's ID, e.g. PT4KHLK (not its number)
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "incident": {
      "type": "string",
      "description": "the incident's ID, e.g. PT4KHLK (not its number)"
    }
  },
  "required": [
    "incident"
  ]
}
acknowledge_incidentRead and write

Acknowledge an incident: someone is on it, so PagerDuty stops escalating it for now.

Approval: Uses your workspace and hire approval settings.

Arguments for acknowledge_incident
ArgumentTypeDetails
incidentRequiredstringthe incident's ID, e.g. PT4KHLK (not its number)
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "incident": {
      "type": "string",
      "description": "the incident's ID, e.g. PT4KHLK (not its number)"
    }
  },
  "required": [
    "incident"
  ]
}
resolve_incidentRead and write

Resolve an incident once it's fixed. Add a note first saying what fixed it.

Approval: Uses your workspace and hire approval settings.

Arguments for resolve_incident
ArgumentTypeDetails
incidentRequiredstringthe incident's ID, e.g. PT4KHLK (not its number)
resolutionOptionalstringwhat fixed it, kept on the incident
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "incident": {
      "type": "string",
      "description": "the incident's ID, e.g. PT4KHLK (not its number)"
    },
    "resolution": {
      "description": "what fixed it, kept on the incident",
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "incident"
  ]
}
reassign_incidentRead and write

Reassign an incident to a person (by email or name) or to an escalation policy (by name).

Approval: Uses your workspace and hire approval settings.

Arguments for reassign_incident
ArgumentTypeDetails
incidentRequiredstringthe incident's ID, e.g. PT4KHLK (not its number)
to_userOptionalstringa PagerDuty user's email or name
to_escalation_policyOptionalstringan escalation policy's name or ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "incident": {
      "type": "string",
      "description": "the incident's ID, e.g. PT4KHLK (not its number)"
    },
    "to_user": {
      "description": "a PagerDuty user's email or name",
      "type": "string",
      "maxLength": 200
    },
    "to_escalation_policy": {
      "description": "an escalation policy's name or ID",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "incident"
  ]
}
add_noteRead and write

Add a note to an incident's timeline: what you found, what you tried, what fixed it.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
incidentRequiredstringthe incident's ID, e.g. PT4KHLK (not its number)
noteRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "incident": {
      "type": "string",
      "description": "the incident's ID, e.g. PT4KHLK (not its number)"
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 25000
    }
  },
  "required": [
    "incident",
    "note"
  ]
}
who_is_on_callRead only

Who's on call now, by escalation level, for a service or for every service this hire can use.

Approval: Uses your workspace and hire approval settings.

Arguments for who_is_on_call
ArgumentTypeDetails
serviceOptionalstringa service's name or ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "a service's name or ID"
    }
  }
}
trigger_incidentRead and write

Open a new incident on a service, which pages whoever is on call. Only for a real problem people must act on now; check list_incidents first so you don't page twice, and use the same dedup_key for the same problem. It waits for a person's approval: Roster asks in the thread and pages, once, when they approve.

Approval: Always asks for approval.

Arguments for trigger_incident
ArgumentTypeDetails
serviceRequiredstringa service's name or ID
summaryRequiredstringwhat's wrong, as the person paged will read it
severityOptional"critical" | "error" | "warning" | "info"See input schema below.Default: "error"
sourceOptionalstringwhere the problem is, e.g. a host or systemDefault: "Roster"
componentOptionalstringSee input schema below.
dedup_keyOptionalstringthe same key for the same problem, so it isn't opened twice
detailsOptionalobjectextra facts, shown on the incident
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "a service's name or ID"
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "what's wrong, as the person paged will read it"
    },
    "severity": {
      "default": "error",
      "type": "string",
      "enum": [
        "critical",
        "error",
        "warning",
        "info"
      ]
    },
    "source": {
      "default": "Roster",
      "description": "where the problem is, e.g. a host or system",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "component": {
      "type": "string",
      "maxLength": 255
    },
    "dedup_key": {
      "description": "the same key for the same problem, so it isn't opened twice",
      "type": "string",
      "maxLength": 255
    },
    "details": {
      "description": "extra facts, shown on the incident",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 2000
      }
    }
  },
  "required": [
    "service",
    "summary"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • Incoming webhooks are supported. Roster can register the connection's callback with the service.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

New Relic

APM, infrastructure, logs and alerts.

PlanetScale

MySQL and Postgres databases, branches and insights.

On this page

1. Make an API key in PagerDuty2. Connect it in Roster3. Give hires access4. Wake hires at once (optional)If something goes wrongTools and permissions reference