# PagerDuty

> Connect PagerDuty so a page joins the Ace incident already open for the same workload, and Ace reads timelines, alerts, on-call and service context during investigations.

Source: https://tryace.dev/docs/integrations/pagerduty

Ace reads PagerDuty to see who was paged, for what, and how the response went. It never adds notes to a page or resolves one.

| | |
| --- | --- |
| Category | Paging |
| Ace reads | Incidents, incident timelines, alerts, on-call, service context, change events, similar incidents |
| Ace can change | Nothing in your incidents (read-only). A full-access key lets Ace add its own webhook subscription. |
| Opens incidents | A page joins the Ace incident already open for the same workload. A high-urgency page opens one if none is open. |
| Setup | Settings form |

## What Ace reads

- PagerDuty incidents around the Ace incident, plus earlier ones still open, with status, urgency, priority, service and assignees.
- Incident timelines: trigger, notifications, acknowledgements, escalations, reassignments and resolve. Ace also reads time to first acknowledgement and responder notes.
- Who was on call for a service's escalation policy, by level.
- The alerts behind an incident, with source integration, dedup key, severity and links.
- Change events tied to an incident, or from shortly before the Ace incident.
- Service dependencies, business services and escalation rules.
- Past similar, related and outlier incidents. This needs PagerDuty AIOps, and Ace says so when your account doesn't have it.

Ace doesn't use PagerDuty to verify a fix, because a page closes when a person resolves it.

For the System Map, Ace discovers your PagerDuty services and their dependencies.

## What Ace can change

Nothing in your PagerDuty incidents. Ace never acknowledges, resolves or annotates a page, and PagerDuty has no actions in Ace. A full-access key lets Ace create its own webhook subscription, and nothing else (see [Wire alerts](#3-wire-alerts)).

## What opens an incident

A page usually joins the Ace incident already open for the same workload, which your alert sources opened. If no incident is open, a high-urgency page opens one.

Events arrive through an account webhook subscription, and Ace also polls PagerDuty every 2 minutes in case a delivery goes missing.

| PagerDuty event | What Ace does |
| --- | --- |
| `incident.triggered`, `incident.reopened` | Joins the Ace incident already open on the workload, or opens one. |
| `incident.acknowledged` | Joins an open incident as evidence only. |
| `incident.priority_updated` | Evidence only. Ace ignores it if the page is already resolved. |
| `incident.resolved` | Marks the page resolved in Ace. |

Low-urgency pages only inform investigations, and so do pages whose incident type you list in **Not reliability incidents**, for example Security or Customer request. If you list **Services**, Ace keeps only pages from those services, even though the subscription covers the whole account.

Severity comes from the page's priority. P1 or SEV1 is critical, P2 or SEV2 high, P3 or SEV3 medium, and P4, P5, SEV4 or SEV5 low. A high-urgency page without a priority is high.

A page reaches an incident only when a workload routes PagerDuty. In the workload's settings, under **Investigation triggers**, turn on **Integration alerts** and check PagerDuty under **Alert sources**. Routing PagerDuty alone doesn't narrow which sources Ace reads for that workload.

## Before you start

- The **admin** role in Ace. See [Roles and permissions](https://tryace.dev/docs/security/roles-and-permissions).
- **Admin** or **Account Owner** in PagerDuty, to create an API key.

## Credentials and permissions

Ace uses one **general access REST API key**. A read-only key is enough if you add the webhook subscription yourself.

| Credential | Where to create it | Access | Why Ace needs it |
| --- | --- | --- | --- |
| API key (needed) | **Integrations** > **Developer Tools** > **API Access Keys** | Read-only general access key | Read incidents, timelines, alerts, on-call, services and change events, and poll for new pages. |
| API key (only for alerts) | Same | Full access general key | Let Ace add and remove its webhook subscription. |

## Set up

### 1. Create the API key

1. As an Admin or the Account Owner, open **Integrations** > **Developer Tools** > **API Access Keys** > **Create New API Key**.
2. Set **Description** to Ace and tick **Read-only API Key**. Leave it unticked only if Ace should add its webhook subscription.
3. Select **Create Key** and copy the key, because PagerDuty shows it only once. Then select **Close**.

### 2. Connect PagerDuty in Ace

1. Open **Settings** > **Data sources** and choose **PagerDuty**.
2. Fill in the form:
   - **API key**: the key you copied.
   - **Service region**: **US (api.pagerduty.com)** or **EU (api.eu.pagerduty.com)**.
   - **Services** (optional): service IDs to keep, comma-separated, for example `PF9KMXH`.
   - **Not reliability incidents** (optional): incident types that inform investigations but never open an Ace incident, comma-separated. Low-urgency pages never open one either.
3. Select **Connect PagerDuty**. Ace saves only if the key passes validation.

### 3. Wire alerts

If the key has full access, Ace adds an account-scoped webhook subscription for incident events, named `ace-<id>`, and stores the signing secret PagerDuty issues. Events from every service reach Ace, including services you add later. Ace rechecks the subscription hourly and removes it when you disconnect, and the **Alerts** section reports what it set up.

If the key is read-only, the **Alerts** section says Ace can't add the subscription, though polling still brings pages in. To add the subscription yourself:

1. Copy the webhook URL Ace shows.
2. In PagerDuty, open **Integrations** > **Generic Webhooks (v3)**, add a subscription at the account scope, and paste the URL.
3. Select `incident.triggered`, `incident.acknowledged`, `incident.reopened`, `incident.resolved` and `incident.priority_updated`, then select **Add Webhook**.
4. Copy the signing secret. PagerDuty shows it once, when it creates the subscription.
5. In Ace, paste it into the signing secret field of the **Alerts** section and select **Save**.

## Confirm it's working

- The connection shows **Connected** once Ace checks the key against your region, reads your services (or each one you listed), and reads incidents.
- The **Alerts** section shows **Waiting for first event** until the first signed delivery turns it **Verified**. Ace polls in the meantime.

## Disconnect

1. In Ace, open **Settings** > **Data sources** > **PagerDuty** and select **Disconnect**. Ace deletes its webhook subscription, and if it can't, it tells you so you can remove `ace-<id>` in PagerDuty yourself.
2. If you added the subscription yourself, delete it in **Integrations** > **Generic Webhooks (v3)**.
3. In PagerDuty, delete the API key.

## Next steps

- [How Ace works](https://tryace.dev/docs/concepts/how-ace-works)
- [incident.io](https://tryace.dev/docs/integrations/incident-io)
- [All integrations](https://tryace.dev/docs/integrations)