> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/integrations/pagerduty.md).

# PagerDuty

Configure the PagerDuty integration in Pharos Admin for on-call escalation.

The PagerDuty integration enables Pharos to create incidents that trigger on-call escalation — phone calls, SMS, and push notifications to ensure critical production issues receive immediate attention.

Once connected, PagerDuty becomes available as a notification action type in [Notification Rules](https://docs.pharos.ai/configuration-guide/notifications.md). When a rule fires and includes a PagerDuty action, Pharos creates an incident in the configured PagerDuty service via the [Events API v2](https://developer.pagerduty.com/docs/events-api-v2/overview/).

{% hint style="danger" %}
**Reserve PagerDuty for True Emergencies**

PagerDuty should only be used for incidents requiring immediate response:

* User-facing failures affecting customers
* Revenue-impacting issues (payment, order management)
* Security incidents
* Complete system outages

If it can wait until morning, use Slack or Teams instead.
{% endhint %}

***

## Accessing PagerDuty Settings

1. Open the **Pharos** app → **Pharos Admin**
2. Select **Integrations** from the left-hand menu
3. Click **PagerDuty**

Before configuration, the page shows the **Enable PagerDuty Integration** toggle in the off state:

![PagerDuty Settings — disabled state with Enable PagerDuty Integration toggle](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-a10a0ab756778ff753b7b97fb1476a97e92f851e%2Fpagerduty-disabled.png?alt=media)

***

## Prerequisites

You need the following from your PagerDuty account before configuring in Pharos:

| Requirement                 | Where to Find It                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PagerDuty API Token**     | PagerDuty → User Icon → My Profile → User Settings → [Create API User Token](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-user-token-rest-api-key), or use a General Access REST API Key from PagerDuty → Integrations → Developer Tools → [API Access Keys](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) |
| **Service Integration Key** | PagerDuty → Services → select your service → Integrations tab → add an **Events API v2** integration → copy the **Integration Key** ([PagerDuty docs](https://support.pagerduty.com/main/docs/services-and-integrations#create-a-generic-events-api-integration))                                                                                                                  |
| **User Email**              | The email address of the PagerDuty user associated with incident creation                                                                                                                                                                                                                                                                                                          |
| **On-call schedule**        | An [escalation policy](https://support.pagerduty.com/main/docs/escalation-policies) assigned to the target service                                                                                                                                                                                                                                                                 |

***

## Configuration

{% stepper %}
{% step %}

### 1. Enable and Enter Credentials

Turn on the **Enable PagerDuty Integration** toggle, then fill in:

* **PagerDuty API Token** — your REST API key (user token or general access key)
* **PagerDuty Service Integration Key** — the Events API v2 integration key from your PagerDuty service
  {% endstep %}

{% step %}

### 2. Let Pharos Connect

After entering both keys, Pharos uses the API token to connect to your PagerDuty account. This connection must succeed before the **Service** dropdown becomes available.
{% endstep %}

{% step %}

### 3. Select User Email and Service

Once connected:

* **User Email** — enter the email of the PagerDuty user who will be associated with incidents created by Pharos
* **Service** — select the PagerDuty service from the dropdown (this list is populated from your PagerDuty account after connection)
  {% endstep %}

{% step %}

### 4. Save

Click **Save** to persist the configuration.
{% endstep %}
{% endstepper %}

![PagerDuty Settings — enabled with API Token, Service Integration Key, User Email, and Service configured](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-fd9843e49fe8cc57af754a09a0ad06f103a0cf6a%2Fpagerduty-enabled.png?alt=media)

{% hint style="warning" %}
You must enter the **API Token** and **Service Integration Key** before the Service dropdown will populate. If you try to select a service before connecting, the dropdown will be empty.
{% endhint %}

***

## Using PagerDuty in Notification Rules

PagerDuty appears as a notification action type in [Notification Rules](https://docs.pharos.ai/configuration-guide/notifications.md) once the integration is enabled. If PagerDuty is not configured, it will not appear in the notification action dropdown.

When a notification rule fires and includes a PagerDuty action:

1. Pharos creates an incident in the configured PagerDuty service via the Events API v2
2. The incident triggers the service's [escalation policy](https://support.pagerduty.com/main/docs/escalation-policies)
3. The on-call engineer is paged via push notification, SMS, or phone call

{% hint style="info" %}
**Combine PagerDuty with other channels.** A common pattern is to pair a PagerDuty action with a Slack or Teams action on the same rule — the on-call engineer gets paged while the broader team sees the issue in a channel for collaboration.
{% endhint %}

***

## Best Practices

| Practice                                | Why                                                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Start without PagerDuty**             | Use only Slack/Teams for 1–2 weeks; observe which issues would genuinely warrant paging                                                              |
| **Add conservatively**                  | Begin with narrow criteria — e.g., monitoring spike rules or Priority = Highest AND Impacted Users Count > 50                                        |
| **Always pair with Slack/Teams**        | On-call gets paged; team sees the issue in a channel for context and collaboration                                                                   |
| **Target fewer than 3 pages per week**  | Over-paging causes alert fatigue and desensitization ([PagerDuty best practices](https://www.pagerduty.com/resources/learn/reducing-alert-fatigue/)) |
| **Tighten filters for false positives** | If more than 20% of pages aren't genuinely urgent, refine your notification rule criteria                                                            |

***

## Sandbox Considerations

**Do not** route sandbox or non-production notifications to PagerDuty. Ensure your notification rules exclude non-production environments from PagerDuty actions.

After a sandbox refresh, verify that PagerDuty notification rules are not inadvertently active — the integration credentials won't carry over, but rule definitions might.

***

## Troubleshooting

| Issue                                         | Cause                                                          | Resolution                                                                                                                                                                                    |
| --------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Service dropdown empty                        | API Token or Integration Key not entered, or connection failed | Enter both keys first; verify the API Token has read access to services                                                                                                                       |
| PagerDuty not in notification action dropdown | Integration not enabled                                        | Enable the toggle in Pharos Admin → Integrations → PagerDuty                                                                                                                                  |
| Incidents not created                         | Invalid Integration Key or service misconfigured               | Verify the Events API v2 integration key; check the service has an active escalation policy                                                                                                   |
| Incidents created but no page                 | No on-call schedule                                            | Configure an [escalation policy](https://support.pagerduty.com/main/docs/escalation-policies) and [on-call schedule](https://support.pagerduty.com/main/docs/schedule-basics) for the service |
| Too many pages                                | Notification rule criteria too broad                           | Tighten filters; use monitoring spike rules or update-based issue rules with high thresholds                                                                                                  |

***

## Related

* [Notification Rules](https://docs.pharos.ai/configuration-guide/notifications.md) — Create rules that trigger PagerDuty actions
* [Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) — All available action types (Slack, Teams, Email, PagerDuty, Webhook)
* [Monitoring](https://docs.pharos.ai/configuration-guide/monitoring.md) — Spike detection rules often paired with PagerDuty for outage scenarios
* [PagerDuty Events API v2](https://developer.pagerduty.com/docs/events-api-v2/overview/) — PagerDuty's event ingestion API used by Pharos
* [PagerDuty Service Setup](https://support.pagerduty.com/main/docs/services-and-integrations) — Creating services and integrations in PagerDuty
