## Why It Matters

PagerDuty is where most security teams already manage incidents and on-call. Connecting it to Kit means vulnerability reports that need immediate attention trigger real pages, not just emails that sit in an inbox overnight.

## What You Need

- Kit account with **VDP Add-on** enabled
- PagerDuty account with permission to create API keys
- A PagerDuty **service** dedicated to VDP alerts (recommended)

## Setup

### 1. Create a PagerDuty API Key

1. Go to **PagerDuty > Integrations > API Access Keys**
2. Click **Create New API Key**
3. Name it "Kit VDP" and copy the key

### 2. Get Your Integration Key

1. Go to **PagerDuty > Services > Your VDP Service > Integrations**
2. Add an **Events API v2** integration (or use an existing one)
3. Copy the **Integration Key** (also called the routing key)

### 3. Connect in Kit

1. Navigate to **VDP > Settings > PagerDuty**
2. Paste both keys and click **Connect to PagerDuty**
3. Kit validates the connection and shows a green status badge

## Alert Events

Configure which events create PagerDuty incidents. Each event has a configurable severity level.

| Event | When It Fires | Default Severity |
|-------|--------------|-----------------|
| New report submitted | A researcher submits a vulnerability report | Info |
| SLA at risk | A report approaches its SLA deadline (checked every 15 min) | Warning |
| SLA breached | A report exceeds its SLA deadline | Warning |
| Critical severity assessed | A report is assessed as critical or super-critical | Critical |
| War room activated | 2+ reports are simultaneously at-risk or breached | Error |

**Deduplication**: Kit uses the report ID as a dedup key. If the same report triggers multiple SLA checks, PagerDuty merges them into one incident instead of creating duplicates.

## On-Call Schedule Sync

When enabled, Kit polls your PagerDuty schedule every 5 minutes and updates the on-call person in Kit automatically.

1. On the PagerDuty settings page, select a schedule from the dropdown
2. Kit matches PagerDuty users to Kit users by **email address**
3. On the On-Call page, select **PagerDuty** mode

**If a PagerDuty user is not found in Kit**: the previous shift stays active, and a warning appears on the settings page.

Manual override is still available in PagerDuty mode. The schedule resumes at the next sync.

## Incident Updates (Bidirectional)

When someone acknowledges or resolves a PagerDuty incident, Kit receives the update via webhook and reflects it on the report timeline.

| PagerDuty Action | Kit Effect |
|-----------------|-----------|
| Incident acknowledged | Report shows "Acknowledged via PagerDuty" status |
| Incident resolved | Report shows "Resolved via PagerDuty" status |

**Important**: PagerDuty status changes do not auto-transition the report. Triage decisions (validating, dismissing, resolving) remain manual in Kit.

### Setting Up the Webhook

1. Copy the **Webhook URL** shown on the PagerDuty settings page
2. In PagerDuty, go to **Integrations > Generic Webhooks (v3)**
3. Create a new webhook subscription with your Kit URL
4. Select events: `incident.acknowledged` and `incident.resolved`

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Connection failed" on save | Invalid API token | Re-generate the token in PagerDuty and paste again |
| Alerts not creating incidents | Event not enabled in alert rules | Check the toggle for each event type on the settings page |
| On-call not syncing | PD user email doesn't match Kit user | Ensure the PagerDuty user's email matches their Kit account email |
| Connection shows red error badge | API token was revoked or expired | Re-connect with a new token; Kit pauses all alerts when auth fails |

## Quick Checklist

- [ ] Create a PagerDuty API key scoped to your VDP service
- [ ] Paste the API key and integration key in **VDP > Settings > PagerDuty**
- [ ] Enable at least one alert rule (recommended: SLA breach + critical assessment)
- [ ] (Optional) Select a PagerDuty schedule for on-call sync
- [ ] (Optional) Set up the webhook in PagerDuty for bidirectional updates
- [ ] Verify by clicking **Test** on the settings page