> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sreagent.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect PagerDuty

> Page PagerDuty from SRE Agent, receive PagerDuty incidents as alerts, and keep acknowledge and resolve in step on both sides.

export const Plan = ({tier}) => <Badge color="blue">{tier} plan</Badge>;

SRE Agent works with PagerDuty in both directions. It can page a PagerDuty service when an alert needs a human, and it can receive PagerDuty's incident events. The two halves are independent, and when both are set up an incident stays in step on both sides.

<Plan tier="Free" />

## Page PagerDuty from SRE Agent

<Steps>
  <Step title="Create an integration in PagerDuty">
    On the PagerDuty service that should receive the incidents, add an **Events API v2** integration
    and copy its integration key (also called the routing key).
  </Step>

  <Step title="Add a PagerDuty target">
    In SRE Agent go to **Settings**, **Outbound Alerting** and click **Add Config**. Enter a
    **Name**, set **Provider Type** to **PagerDuty**, paste the key into **Routing Key (PagerDuty)**
    and click **Save Config**.
  </Step>

  <Step title="Choose when it pages">
    Either open an alert and click **Page via** followed by the target name, or click **Add Rule**
    under **Automatic Escalation Rules**. A rule picks the alerts to page by source, severity or
    labels, and **Escalate after (minutes)** sets the wait, or leave it empty to page at once.
    **Step order** lets you chain targets so the next step waits for an acknowledgement.
  </Step>
</Steps>

Severity maps across as critical to critical, high to error, medium to warning and anything else to info. The alert's title, description, labels and a link back to SRE Agent go with the page.

## What stays in step

When an alert has been paged to PagerDuty, status changes carry over:

| In SRE Agent | In PagerDuty |
| - | - |
| You page the alert | An incident opens, with an incident key that starts with `sre-agent-`. |
| You acknowledge the alert | The incident is acknowledged. |
| You resolve the alert | The incident is resolved. |

A change is sent once, when the status really changes. A repeat delivery of an alarm that is already acknowledged or resolved sends nothing. If an alert was paged to more than one PagerDuty service, a status that came from PagerDuty is forwarded to the others, so none of them keeps escalating.

## Receive PagerDuty incidents in SRE Agent

<Steps>
  <Step title="Copy your webhook URL">
    Open **Integrations**, **Webhooks** and find the **PagerDuty** card. Copy the endpoint URL, which looks like `https://sreagent.app/webhooks/pagerduty/<token>`.
  </Step>

  <Step title="Add a webhook in PagerDuty">
    In PagerDuty go to **Integrations**, **Generic Webhooks (v3)** and click **New Webhook**. Paste the URL into **Webhook URL** and subscribe to `incident.triggered`, `incident.acknowledged` and `incident.resolved`. Other event types are accepted and ignored.
  </Step>

  <Step title="Save the signing secret">
    Copy the webhook's signing secret, paste it into **Signing secret** on the PagerDuty card in SRE Agent and click **Save secret**. The secret needs at least 16 characters. Deliveries are then verified against their signature. Without a secret, the token in the URL is the only check, unless you have an approved runbook that runs automatically. Then PagerDuty deliveries must be signed, and unsigned ones answer 401. **Replace secret** and **Clear** manage it later.
  </Step>
</Steps>

## What you see

An incident that started inside PagerDuty (from a monitoring integration there) becomes an alert with the source `pagerduty`. It is handled like any other new alert, with a Slack message, an investigation and your rules.

| PagerDuty event | Alert in SRE Agent |
| - | - |
| `incident.triggered` | Created as active. PagerDuty urgency high becomes severity high, low becomes low, anything else medium. |
| `incident.acknowledged` | Acknowledged. The timeline notes who acknowledged it in PagerDuty. |
| `incident.resolved` | Resolved. A resolve by a person in PagerDuty counts as a person resolving here. A resolve by PagerDuty's own automation counts as an automatic recovery. |

For an incident that SRE Agent opened itself, the events act on the existing alert and never create a second one. The alert page gains a **View in PagerDuty** button once PagerDuty reports the incident. If the alert has a Slack thread, an acknowledgement is noted once in it ("Acknowledged in PagerDuty by Jane Doe") and a resolve posts the usual "Alert Resolved" reply.

<Note>
  An alert that came from PagerDuty is never paged to a PagerDuty target, because its responders are
  already paged. Slack, webhook and on-call targets still page. If you press **Page via** on such an
  alert, SRE Agent tells you why nothing was sent.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The webhook answers 200 but no alert appears">
    Check that the subscription includes the three incident events. Other event types answer 200 and
    do nothing by design. PagerDuty's webhook delivery log shows what it sent.
  </Accordion>

  <Accordion title="Deliveries answer 401">
    A request with a wrong or missing signature answers 401. A missing signature is refused whenever
    you have an approved runbook that runs automatically. The signing secret saved in SRE Agent does
    not match the one PagerDuty shows for the subscription. Replace the secret on the PagerDuty
    card.
  </Accordion>

  <Accordion title="Acknowledging in PagerDuty does not acknowledge the alert">
    The two sides match on the incident key, which starts with `sre-agent-`. That is only true when
    SRE Agent opened the incident through a PagerDuty target. An incident created by hand in
    PagerDuty becomes its own alert. Also check that the webhook URL belongs to the same
    organization that owns the alert.
  </Accordion>

  <Accordion title="The alert has no View in PagerDuty button">
    The button appears once PagerDuty delivers an event for the incident, so the subscription must
    include `incident.triggered`.
  </Accordion>

  <Accordion title="Acknowledging here does not acknowledge in PagerDuty">
    SRE Agent forwards the change using the record of the original page. An incident paged by a
    target that has since been deleted cannot be closed from here, so close it in PagerDuty.
  </Accordion>
</AccordionGroup>

## Related

* [Triage alerts](/guides/respond/alerts): how alerts are handled once they arrive.
* [Set up on-call](/guides/respond/on-call): use built-in on-call instead of PagerDuty.
* [Webhook endpoints](/guides/reference/webhook-endpoints): how webhook signing works for every source.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.