PagerDuty
The PagerDuty integration lets Helios agents call PagerDuty's REST API, Events API, and its Slack, Microsoft Teams, Jira Cloud and SCIM APIs, and start workflows on supported incident and service events.
What your agents can do
Helios agents can look up who is on call, manage incidents and services, and start workflows on supported PagerDuty events. API access depends on your key or token, the authorizing user's role, and your PagerDuty account's features.
- Find who is on call for a service, schedule, or escalation policy
- Create an incident from an alert or from something an agent found
- Acknowledge, resolve, reassign, or escalate incidents, and add notes and status updates
- Summarize the open incidents for a service or team
- Open a dedicated Slack channel or Microsoft Teams chat for an incident
- Change services, schedules, escalation policies, and event orchestrations
- Send alert and change events through the Events API
The Events API on events.pagerduty.com doesn't use your key or token. Each event needs the integration key of an Events API v2 integration on a service, sent as its routing_key. Give the agent that key in the workflow's prompt.
Calls to the Slack, Microsoft Teams and SCIM APIs need the /integration-slack, /integration-ms-teams and /scim/v2 path prefixes respectively. Slack connection calls need the full URL under https://app.pagerduty.com/integration-slack/. Events API v2 calls need the full URL under https://events.pagerduty.com/v2/.
The Jira Server integration API and PagerDuty's MCP server are not supported. The Jira Server API takes only a Classic User OAuth token, which neither connection method has. The MCP server expects a client to open a session before it calls tools, which a single API call can't do. Its tools run the same REST API that the agent already reaches.
Authentication
| Method | Type | Description |
|---|---|---|
| PagerDuty API Key | API Key | A REST API key or user token, and the email of a user in your PagerDuty account |
| Your own PagerDuty OAuth app | OAuth 2.0 | A Scoped OAuth app that you register in your PagerDuty account |
See Integration authentication for how credentials are stored and injected.
PagerDuty API Key
You need the Admin, Global Admin, or Account Owner role to create a general access key. Triggers need a key that can create webhook subscriptions. That is a general access key with full access, or the user token of an Admin, Global Admin, or Account Owner.
- In PagerDuty, open Integrations → Developer Tools → API Access Keys and click Create New API Key. Leave Read-only API Key unchecked.
- Copy the key. PagerDuty shows it only once.
- In Helios, choose PagerDuty API Key and paste the key into PagerDuty API Key.
- In From Email, enter the email of a user in your PagerDuty account.
- Save.
If your account has Advanced Permissions, a user token also works. Create one under My Profile → User Settings → Create API User Token. It can do only what its user can do.
A general access key with full access reaches the most APIs, with these exceptions from PagerDuty's API reference:
- The SCIM API takes only a general access key, so a user token can't call it.
- The Slack integration API takes only a user token of an Account Owner or Global Admin, so a general access key can't call it.
PagerDuty needs a From email to create or change an incident and to add a note, and it records that user as the one who made the change. Helios sends the email from From Email with every request. If you delete the key in PagerDuty, create a new one and enter it through Manage.
A separate PagerDuty user for Helios keeps the agent's changes apart from yours. Use its email as the From email.
Your own PagerDuty OAuth app
You need the Manager, Global Admin, or Account Owner base role to register an app. Triggers also need the user who authorizes the app to be an Admin, Global Admin, or Account Owner, because Helios creates the webhook subscription as that user.
-
In PagerDuty, open Integrations → Developer Tools → App Registration and click New App. Enter a name and description, and finish the wizard.
-
In the app's Functionality section, click Add on the OAuth card and choose Scoped OAuth.
-
Add this redirect URL:
https://api.heliosapp.com/integrations/pagerduty/oauth_callback -
Turn on the scopes in the table below. Turn on the scopes for the APIs and events you need. If App Registration doesn't list a scope, leave it off. If you will check Admin access in Helios, also turn on the admin scopes.
-
Save, and copy the client ID and client secret.
-
In Helios, choose Your own PagerDuty OAuth app and enter them in Client ID and Client Secret.
-
Check Admin access if you turned on the admin scopes.
-
Save, then authorize the app in PagerDuty.
Helios asks for every scope below, and PagerDuty grants the ones the app has. A missing scope limits what's available. The agent can't call the endpoints it covers, and triggers that need it show as unavailable. Helios needs abilities.read to test the connection, and doesn't connect without it.
Triggers need webhook_subscriptions.read and webhook_subscriptions.write. Each event also needs the scope that covers it:
incidents.readfor incident eventsincident_workflows.readforincident.workflow.startedandincident.workflow.completedservices.readfor service eventspd_advance.writeforscribe.summary.created
| Scopes | What they're for |
|---|---|
abilities.read | Testing the connection, and checking which features the account has |
incidents.read, incidents.write | Incidents, notes, log entries, responders, status updates, and paused incident reports |
incident_types.read, incident_types.write, custom_fields.read, custom_fields.write, priorities.read | Incident types, custom fields on incidents and services, and priorities |
incident_workflows.read, incident_workflows.write, incident_workflows:instances.write | Incident workflows, and starting them on an incident |
oncalls.read, schedules.read, schedules.write, escalation_policies.read, escalation_policies.write | On-call shifts, schedules, and escalation policies |
services.read, services.write, maintenance_windows.read, maintenance_windows.write | Services, business services, service dependencies, alert grouping settings, and maintenance windows. The maintenance window endpoints accept services.read and services.write |
teams.read, teams.write, users.read, users.write, users:contact_methods.read, users:contact_methods.write, users:sessions.read, users:sessions.write, licenses.read, notifications.read, oauth_delegations.read, oauth_delegations.write | Teams, users, contact methods, sessions, licenses, notifications, and app authorizations |
event_orchestrations.read, event_orchestrations.write, event_rules.read, event_rules.write, contextual_data.read, contextual_data.write, event_enrichments.read, event_enrichments.write, change_events.read, change_events.write | Event orchestrations, rulesets, event enrichment, and change events |
status_pages.read, status_pages.write, status_dashboards.read, subscribers.read, subscribers.write | Status pages, status dashboards, and subscribers |
addons.read, addons.write, extensions.read, extensions.write, extension_schemas.read, vendors.read, workflow_integrations.read, workflow_integrations:connections.read, workflow_integrations:connections.write, jira_cloud_accounts.read, jira_cloud_rules.read, jira_cloud_rules.write | Add-ons, extensions, vendors, workflow integrations, and the Jira Cloud integration |
analytics.read, audit_records.read, standards.read, standards.write, recommendations.read, recommendations.write, templates.read, templates.write, tags.read, tags.write | Analytics, audit records, service standards, recommendations, templates, and tags |
copilot:chat.read, copilot:chat.write, pd_advance.write | PagerDuty AI features, and the scribe.summary.created event |
session_configurations.read | Reading session timeout settings |
webhook_subscriptions.read, webhook_subscriptions.write | Creating and removing the webhook subscription for triggers |
Admin access adds these scopes. PagerDuty lets only Account Owners and Global Admins use the IP allow list endpoints, and only Account Owners and admins change session timeouts.
| Scopes | What they're for |
|---|---|
ip_allow_lists.read, ip_allow_lists.write | IP allow lists for user sessions |
session_configurations.write | Changing session timeouts |
An OAuth token acts as the user who authorized the app, so the agent can do only what both the scopes and that user's role allow. This method can't reach some APIs:
- The SCIM API and the Microsoft Teams integration API. PagerDuty documents SCIM for general access keys and app tokens, and the Teams integration API for API keys. This method uses a user token.
- Endpoints that PagerDuty's API reference lists without a Scoped OAuth scope, such as Automation Actions and shift-based schedules (
/v3/schedules). They may not work with Scoped OAuth. - The analytics endpoints that need
analytics.write, and SRE agent memories. PagerDuty doesn't offer the scopes they need to apps.
Use the API key method for these.
PagerDuty records changes as the user who authorized the app, so this method needs no From email. Access tokens last one day, and refresh tokens expire after 30 days without use. Helios schedules a weekly refresh while the connection is active. After one year, PagerDuty requires you to authorize the app again. Open the connection and connect again.
If you rotate the client secret, enter the new one through Manage. After that, or after you change the scopes or Admin access, connect again.
EU service region
PagerDuty forwards requests from api.pagerduty.com to the EU service region when it detects an EU API key, so the API key method works for EU accounts. PagerDuty doesn't document this forwarding for OAuth tokens, so Your own PagerDuty OAuth app may not work for an account in the EU region.
Triggers
PagerDuty can start a Workflow when something happens to an incident or a service. Helios creates an account-level webhook subscription with the description Helios in PagerDuty when you save the connection, and requests the supported event types allowed by the connection's scopes. Deleting the connection removes the subscription.
Creating the subscription needs the permissions described above: a general access key with full access, or a user token or OAuth app authorized by an Admin, Global Admin, or Account Owner. A read-only key can't create it, and can't change incidents either. If PagerDuty refuses the subscription, every event shows as unavailable with PagerDuty's message, and Helios removes the connection's older subscription. If PagerDuty won't let Helios remove it, Helios rejects its deliveries. PagerDuty allows up to 10 account-level subscriptions, and each Helios connection uses one. When the account has 10, Helios deletes the connection's old subscription before it creates the new one. Some accounts don't support every event type. When PagerDuty refuses one, Helios subscribes to the rest, and the trigger picker shows the event as unavailable on the connection. Events whose OAuth scope is missing show as unavailable too.
| Event | Description | Filters |
|---|---|---|
incident.triggered | An incident was triggered | service, team, urgency, priority (pattern) |
incident.acknowledged | An incident was acknowledged | service, team, urgency, priority (pattern) |
incident.unacknowledged | An incident was unacknowledged | service, team, urgency, priority (pattern) |
incident.escalated | An incident was escalated | service, team, urgency, priority (pattern) |
incident.reassigned | An incident was reassigned to another user | service, team, urgency, priority (pattern) |
incident.delegated | An incident was reassigned to another escalation policy | service, team, urgency, priority (pattern) |
incident.reopened | An incident was reopened | service, team, urgency, priority (pattern) |
incident.resolved | An incident was resolved | service, team, urgency, priority (pattern) |
incident.priority_updated | An incident's priority changed | service, team, urgency, priority (pattern) |
incident.service_updated | An incident moved to another service | service, team, urgency, priority (pattern) |
incident.incident_type.changed | An incident's type changed | service, team, urgency, priority (pattern) |
incident.conference_bridge.updated | An incident's conference bridge changed | none |
incident.custom_field_values.updated | An incident's custom field values changed | none |
incident.annotated | A note was added to an incident | note contains |
incident.status_update_published | A status update was published for an incident | message contains |
incident.responder.added | A responder was asked to join an incident | user (pattern) |
incident.responder.replied | A responder replied to a request to join an incident | user (pattern) |
incident.role.assigned | An incident role was assigned or unassigned | role (pattern), user (pattern) |
incident.task.created | An incident task was created | user (pattern) |
incident.task.updated | An incident task was updated | user (pattern) |
incident.task.completed | An incident task was completed | user (pattern) |
incident.action_invocation.created | An automation action was invoked on an incident | automation action (pattern) |
incident.action_invocation.updated | An automation action invocation was updated | automation action (pattern) |
incident.action_invocation.terminated | An automation action invocation ended | automation action (pattern) |
incident.workflow.started | An incident workflow started | service, workflow (pattern) |
incident.workflow.completed | An incident workflow completed | service, workflow (pattern) |
scribe.summary.created | Scribe Agent created a meeting summary for an incident, or failed to | none |
service.created | A service was created | team |
service.updated | A service was updated | service, team |
service.custom_field_values.updated | A service's custom field values changed | service |
service.deleted | A service was deleted | service, team |
All filters are optional. An empty filter matches every event.
- Service matches the service, chosen from a list of your services. For incident events it's the incident's service, and for service events it's the service itself.
- Team matches when any of the incident's or service's teams is selected.
- Urgency is High or Low.
- Priority matches the priority's name, such as
P1orP*. It's a pattern, and case matters. An incident without a priority doesn't match. - Note contains and Message contains match when the note or status update includes any of the values, ignoring case.
- User matches the name of the responder, the task's assignees, or the user given the role. Role, Automation action, and Workflow match the name of the role, action, or incident workflow. These are patterns, and case matters.
For notes, status updates, responders, roles, tasks, automation actions, and changes to an incident's conference bridge or custom fields, PagerDuty sends only a reference to the incident. So those events have no service, team, urgency, or priority filters. For changes to a service's custom fields, PagerDuty sends the service without its teams, so that event has no team filter.
Some events come from features that only some PagerDuty plans include:
- Responders, conference bridges, and custom fields on incidents are on the Business, Enterprise for Incident Management, and Digital Operations (Legacy) plans. Custom fields on services are on Business and Enterprise for Incident Management.
- Incident workflows are on Business, Enterprise for Incident Management, and Digital Operations (Legacy). Professional accounts can create one workflow. PagerDuty sends
incident.workflow.startedandincident.workflow.completedonly for a workflow started by a conditional trigger. A workflow started through the API runs, but sends neither event. - Automation actions need Runbook Automation.
- Scribe Agent is a PagerDuty AI feature.
Deliveries are verified with the HMAC-SHA256 X-PagerDuty-Signature header, signed with the secret PagerDuty returns when Helios creates the subscription. Events more than 48 hours old are rejected.
PagerDuty retries a failed delivery for up to 48 hours. After three deliveries in a row are dropped, PagerDuty disables the subscription for 24 hours and marks it Needs Attention. Re-enable it with Enable on the subscription's page in PagerDuty, or save the connection in Helios again to create a new one. See PagerDuty's webhook behavior.
An agent that changes what a trigger watches can start another run. Adding a note starts incident.annotated. Acknowledging, reassigning, or resolving an incident starts that event. Changing its priority starts incident.priority_updated, publishing a status update starts incident.status_update_published, and changing a service starts service.updated. Use filters, and say in the prompt which events to ignore, such as notes the agent wrote. See Guarding against events you don't want.
Check that it works
- The connection: after you save, the connection's status shows Connected. Error means the connection test failed. Open the connection to see the error.
- The subscription: in PagerDuty, open Integrations → Generic Webhooks (v3). A subscription with the description Helios should be listed. If it's missing, Helios couldn't create it. Check the permissions under Triggers, then save the connection again.
- A trigger:
- Add
incident.triggeredto a workflow with no filters. - Trigger a test incident on a PagerDuty service.
- Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
- Add
Common errors
| What you see | Cause | Fix |
|---|---|---|
| The connection's status shows Error | The key was deleted, the OAuth app's access was revoked, or the token expired after 30 days without a refresh | Create a new key and enter it through Manage, or connect the OAuth app again |
PagerDuty did not grant the abilities.read scope | The OAuth app doesn't have abilities.read, which Helios needs to test the connection | Turn on the scopes in the app, then connect again |
Authorize the PagerDuty OAuth app before using this connection | The OAuth authorization wasn't finished | Open the connection and connect again |
An agent gets Requester User Not Found when it changes an incident | From Email isn't the email of a user in the PagerDuty account | Enter a user's email through Manage |
| No Helios subscription under Generic Webhooks (v3), and no runs start | The key is read-only, the user token or authorizing user isn't an Admin, Global Admin, or Account Owner, the OAuth app lacks webhook_subscriptions.write, or the account already has 10 account-level subscriptions | Fix the permission or remove an unused subscription, then save the connection again |
| An event shows as unavailable in the trigger picker | The OAuth app doesn't have the scope the event needs, or PagerDuty doesn't support the event type on this account | Turn on the scope and connect again, or check that your plan includes the feature and save the connection again |
| The Helios subscription shows Needs Attention | PagerDuty disabled it after failed deliveries | Click Enable on the subscription, or save the connection again |
| No run starts, and the subscription looks fine | The filters don't match the event, or the account's plan doesn't include the feature that sends it | Try the trigger with no filters, then add filters back one at a time |
Limits
PagerDuty allows 960 REST API requests per minute for each account API key, for each user across their keys, and for each app per authorizing user. See PagerDuty's rate limits.
The Events API v2 allows about 120 events per minute for each integration key. See PagerDuty's Events API rate limits.
Last updated on
Linear
The Linear integration lets Helios agents query and change your Linear workspace through its GraphQL API, and run agents automatically when issues, comments, projects, cycles, documents, initiatives, customers, or releases are created, updated, or removed.
Notion
The Notion integration lets Helios agents search the Notion API and call any endpoint to create pages, update database entries, query data, search content, and comment.