---
title: PagerDuty
description: Route incidents to PagerDuty over the Events API v2 — a firing alert opens a PagerDuty incident, recovery resolves the same one.
canonical: https://watchfor.io/docs/notifications/pagerduty
---

# PagerDuty

Route incidents to PagerDuty over the Events API v2 — a firing alert opens a PagerDuty incident, recovery resolves the same one.

WatchFor integrates with the **PagerDuty Events API v2**. A firing alert
**triggers** a PagerDuty incident; when the underlying problem clears,
WatchFor **resolves the same incident automatically** — so on-call isn't left
paging over something that's already fixed.

## Setup

### Create (or open) a PagerDuty service
In PagerDuty, go to **Services → Service Directory** and add or open the
service that should receive WatchFor alerts.

### Add an Events API V2 integration
On the service's **Integrations** tab, add an integration of type
**Events API V2**. PagerDuty generates a 32-character **Integration Key**.

### Add the channel in WatchFor
Go to **Alerting → Channels & contacts → Add Channel → PagerDuty**, paste the Integration
Key as the **Routing Key**, and pick your **Service Region** — leave it as
*US / Global* unless your PagerDuty account is in the EU region. Attach the
[contact groups](/docs/notifications/contact-groups) it should serve and
save.

### Send a test
**⋯ → Send test** — a triggered incident titled `[TEST] …` appears in
PagerDuty within a few seconds. **Resolve it in PagerDuty yourself**: tests
never send a resolve event.

> **Warn**
>
> Routing keys are **region-specific**. If your PagerDuty account is in the EU
> service region, choose **EU** (`events.eu.pagerduty.com`) — a US key sent to
> the EU endpoint, or vice versa, is rejected.

## Lifecycle

| In WatchFor | Sent to PagerDuty |
| --- | --- |
| Incident fires (confirmed) | `trigger` |
| Repeat reminder (if enabled on the monitor) | another `trigger` with the same dedup key — updates the existing incident, doesn't open a second one |
| Incident resolves — recovery or administrative close | `resolve` |
| Incident acknowledged in WatchFor | nothing — acknowledge is not synced in either direction |

Every event carries the deduplication key
`watchfor-rule-<rule id>-scheduler-<monitor id>`, so each alert rule on each
monitor maps to exactly one PagerDuty incident: re-fires update it, and the
recovery closes precisely that one. Two rules firing on the same monitor open
two PagerDuty incidents.

PagerDuty channels are never [grouped](/docs/notifications#grouping-during-a-storm):
each incident is its own event, so PagerDuty's own grouping and auto-resolve
work as designed.

## What PagerDuty receives

- **Summary** — the standard title (`🔴 DOWN: API (prod)`).
- **Severity** mapped one-to-one: critical → `critical`, warning →
  `warning`, info → `info`.
- **Source** = the monitor's target, **component** = monitor type, **group** =
  monitor name, **class** = `alert`.
- **Custom details** — `incident_id`, `rule_id`, `scheduler_id`, `status`,
  `fire_count`, `started_at`, `monitor_name`, `target`, `probe_type`,
  `diagnosis`, `expected`, `detected_value`, `expression` (the rule
  expression), `confirmed_by` (locations), `incident_url`, `rule_version`
  (and `updated_rule_version` if the rule changed mid-incident), plus
  `flapping`, `duration`, `resolved_at` and `resolved_value` when relevant.
- A **"WatchFor" link** on the incident header (trigger events) that opens
  the incident page.

## Severity and escalation tips

- Put only **Critical** in the channel's severity filter so warnings don't
  page anyone; send warnings to a chat channel instead.
- Map PagerDuty urgency on the PagerDuty side (service → urgency rules) —
  WatchFor's `critical`/`warning` severities give you the signal to key off.
- WatchFor's own [on-call and escalations](/docs/alerting/on-call) can run
  alongside PagerDuty or replace it for smaller teams.

## Troubleshooting

- **Test fails / nothing in PagerDuty** — double-check the Routing Key is an
  **Events API V2** integration key (not an Events API v1 key or a REST API
  token), and that the Service Region matches your account. The recorded
  error in [notification history](/docs/notifications/history) shows the
  HTTP status PagerDuty returned.
- **Incident opens but never resolves** — the resolve is sent through the
  same channel that triggered. If the channel was disabled, deleted, or its
  severity filter changed between trigger and recovery, the resolve never
  went out; resolve it in PagerDuty by hand.
- **A `[TEST]` incident is stuck open** — expected; resolve it manually.

---

Canonical page: https://watchfor.io/docs/notifications/pagerduty · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt