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

# PagerDuty

> Trigger PagerDuty incidents from Tallwatch monitor failures through the Events API v2.

Tallwatch sends incident events to PagerDuty through the [Events API v2](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview). From there, your PagerDuty escalation policy decides who gets paged and how. Setup takes about two minutes once you know which service should receive the alerts.

## Before you start

* A PagerDuty account with the **Events API v2** integration (any paid tier, plus the free trial).
* The PagerDuty **service** these alerts belong to. A service represents one thing that can fail, so pick or create the matching one.

## 1. Add the integration in PagerDuty

<Steps>
  <Step title="Open the service">
    Go to **Services → Service Directory** and open the service that should receive Tallwatch alerts.
  </Step>

  <Step title="Add an Events API V2 integration">
    On the **Integrations** tab, click **Add an integration**, search for **Events API V2**, and select it.
  </Step>

  <Step title="Copy the integration key">
    PagerDuty shows a 32-character **Integration Key**. Copy it.
  </Step>
</Steps>

<Note>
  PagerDuty's docs sometimes call this the "Routing Key." It's the same value. Tallwatch's form labels it **Integration key**.
</Note>

## 2. Add the channel in Tallwatch

<Steps>
  <Step title="Open the channels page">
    Go to **Settings → Alerts → Channels** and click **Add channel**.
  </Step>

  <Step title="Pick PagerDuty">
    Choose the PagerDuty kind and name it for the service, like `PagerDuty: billing prod`.
  </Step>

  <Step title="Paste the key and test">
    Put the 32-character key in **Integration key**, click **Save**, then **Send test alert**. A triggered incident should open in PagerDuty within seconds.
  </Step>
</Steps>

<Tip>
  Resolve the test incident in PagerDuty afterward, or your on-call gets paged for a dry run.
</Tip>

## How events map

Tallwatch translates incident lifecycle events into PagerDuty event actions:

| Tallwatch event             | `event_action` | Result in PagerDuty                               |
| --------------------------- | -------------- | ------------------------------------------------- |
| `incident.opened`           | `trigger`      | New incident; the escalation policy fires         |
| `incident.resolved`         | `resolve`      | The linked PagerDuty incident is resolved         |
| Manual resolve in Tallwatch | `resolve`      | The linked PagerDuty incident is resolved         |
| Acknowledge in Tallwatch    | none           | PagerDuty stays open; acknowledge it in PagerDuty |

The `dedup_key` is `tallwatch:incident:<id>`, so the `resolve` ties back to the incident the `trigger` opened rather than spawning a duplicate.

## What the alert carries

A triggered PagerDuty incident with:

* A summary of `<monitor name> <event>`, for example `API healthcheck incident.opened`
* Severity `critical` on open
* `source` set to the monitor's URL (or its name, for monitors without one)
* `component` set to the monitor type and `group` to your workspace slug
* `custom_details` with the full event, monitor, org, incident, and last-check data, so on-call can see the failing regions and error class without leaving PagerDuty

## Acknowledge and resolve

Resolving in Tallwatch sends a `resolve` to PagerDuty. Acknowledging in Tallwatch does not: in v1, the only actions sent to PagerDuty are `trigger` and `resolve`. Acknowledge the page in PagerDuty itself. Two-way sync of acknowledgements is planned for v1.1.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The test dispatched, but no incident in PagerDuty">
    Check the dispatch history. A 4xx usually means the integration key was revoked or pasted wrong, so regenerate the integration and update Tallwatch.

    If PagerDuty returned 202 but no incident shows, the service may be suppressing a re-trigger because the same incident resolved recently. Wait the dedup window out, or trigger from a different monitor.
  </Accordion>

  <Accordion title="The dispatch shows `failed`">
    Open the row for the error. Common ones:

    * A `pagerduty_error` response, often a disabled integration. Re-enable it on the service's Integrations tab.
    * A 400, which means PagerDuty rejected the request body. Open an issue with the error text.
  </Accordion>

  <Accordion title="The PagerDuty incident isn't auto-resolving">
    Auto-resolve depends on the `resolve` carrying the same `dedup_key` as the original `trigger`. If the incident was resolved manually in PagerDuty first, PagerDuty treats the key as stale and a later trigger opens a fresh incident instead.
  </Accordion>

  <Accordion title="Can I send to multiple PagerDuty services?">
    Yes. Add one Tallwatch channel per service, each with its own integration key, and bind them to different monitors or policies.
  </Accordion>
</AccordionGroup>

## Reference

| Property        | Value                                                                   |
| --------------- | ----------------------------------------------------------------------- |
| Channel kind    | `pagerduty`                                                             |
| Required config | `integration_key` (32-character Events API v2 routing key)              |
| Endpoint        | `https://events.pagerduty.com/v2/enqueue`                               |
| Dedup key       | `tallwatch:incident:<id>`                                               |
| Severity        | `critical` on open                                                      |
| Delivery        | Immediate, no proactive rate limit                                      |
| Retry           | Up to 3 inline attempts on 5xx, 429, network, or timeout, then `failed` |