PagerDuty Integration
Connect PagerDuty to receive VDP alerts, sync on-call schedules, and track incident status in Kit.
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 instead of emails that sit in an inbox overnight.
What You Need
- Active Kit subscription
- PagerDuty account with permission to create API keys
- A PagerDuty service dedicated to VDP alerts (recommended)
Setup
1. Create a PagerDuty API Key
- Go to PagerDuty > Integrations > API Access Keys
- Click Create New API Key
- Name it “Kit VDP” and copy the key
2. Get Your Integration Key
- Go to PagerDuty > Services > Your VDP Service > Integrations
- Add an Events API v2 integration (or use an existing one)
- Copy the Integration Key (also called the routing key)
To send each component’s pages to the team that owns it, use an Event Orchestration’s integration key instead. See Route Pages to the Owning Team.
3. Connect in Kit
- Navigate to VDP > Settings > PagerDuty
- Paste both keys and click Connect to PagerDuty
- Kit validates the connection and shows a green status badge
Alert Events
Configure which events page PagerDuty. Each event has its own severity, Warning until you change it.
| Event | When It Fires |
|---|---|
| New report submitted | A researcher submits a vulnerability report |
| SLA at risk | A report approaches its SLA deadline (checked every 15 min) |
| SLA breached | A report exceeds its SLA deadline |
| Critical severity assessed | You validate a report at one of your escalation severities (Critical and Super Critical by default) |
| Report validated | You validate any report |
| Stalled report escalated | A stalled report is escalated to your program admins |
What a page says: the event, the assessed severity, the report’s component and its ID, for example SLA breached · Critical · Payments API — rpt_8Kd2. The incident’s source names your program. Kit never copies researcher-written text (title, vulnerability type, description) into PagerDuty, so a report can’t put its own words on your responder’s phone. A restricted report pages as Restricted report needs attention — rpt_8Kd2, without its event, severity or component. Its page keeps the severity its alert rule sets, so on-call still gets the right urgency.
One Incident per Report
Kit keys every page to the report, so each report has at most one open PagerDuty incident. The first event opens it. While it’s open, later events on the same report don’t page again: PagerDuty adds each one to the incident’s alert log as another trigger, so the incident holds the report’s history. Validating a Critical report with both Critical severity assessed and Report validated on pages once, not twice.
When a report gets worse: PagerDuty keeps the highest severity it receives for an incident. If Report validated opened the incident at Warning and Critical severity assessed later arrives at Critical, the incident becomes Critical. On a service set to dynamic notifications, that raises the incident from low to high urgency, so it follows your high-urgency notification rules. On a service with a fixed urgency, the later event only lands in the alert log, and PagerDuty doesn’t notify again for an incident someone already acknowledged. To be paged when a report turns critical, use dynamic notifications and give Critical severity assessed a higher severity than your other rules.
Repeat SLA breached triggers are also capped before they ever reach PagerDuty, by your program’s breach-alert budget: three repeats, six hours apart, by default.
Route Pages to the Owning Team
Kit sends every page to one integration key. With a service’s key, every page reaches that service. To page the team that owns a report’s component, paste an Event Orchestration integration key into Kit instead, and let the orchestration pick the service. Orchestration routing rules are available on every PagerDuty plan.
- In PagerDuty, go to Event Orchestration (under Configuration > Events & Routing, or AIOps on some accounts) and create an orchestration
- Open its Integrations and copy the integration key
- In Kit, paste it as the Integration Key on VDP > Settings > PagerDuty
- Add one Service Route per component, with the condition
event.custom_details.component_id matches 'cmp_…'. Copy each component’s ID from VDP > Program Settings > Components. The ID stays the same when you rename a component, so a route on it keeps working - Edit the catch-all route to send unmatched events to your triage service
Don’t skip the catch-all: by default, PagerDuty suppresses a page that matches no route, so it never notifies anyone. New report pages usually arrive before anyone assigns a component, and restricted reports never carry one, so both reach only the catch-all.
Routing follows the incident’s first page: an incident stays with the service it opened in, and the report’s later pages join it there. Changing a report’s component pages nobody. The report’s next page resolves the open incident in its old service and opens a new incident for the new component, so the report never has two incidents open. A review agent’s page joins the open incident instead of moving it. Only the component you confirm on the report routes a page, never a suggested one.
| Field | What Kit sends |
|---|---|
component |
The report’s component name, left out when the report has none or is restricted |
group |
Your program’s name |
class |
The event: new_report, sla_at_risk, sla_breach, critical_assessment, report_validated, escalation, or agent_escalation for a review agent’s possible critical. Always restricted_report on a restricted report |
custom_details.component_id |
The component’s ID, cmp_…
|
custom_details.component |
The component’s name |
custom_details.program_id |
Your program’s ID |
custom_details.report_id |
The report’s ID, rpt_…
|
custom_details.severity |
The assessed severity, left out on restricted reports |
A restricted report’s page names no component, assessed severity or event: only the report’s ID, your program, and restricted_report as the event.
PagerDuty’s dynamic routing can also pick a service from an event field, but only on orchestrations with the AIOps add-on, and it drops an event whose routing field it can’t read. One route per component is the safer setup.
On-Call Schedule Sync
When enabled, Kit polls your PagerDuty schedule every 5 minutes and updates the on-call person in Kit automatically.
- On the PagerDuty settings page, select a schedule from the dropdown
- Kit matches PagerDuty users to Kit users by email address
- 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. Validating, dismissing, or resolving a report is a separate action in Kit.
Closing a Report Resolves Its Incident
When a report leaves the open pipeline (you resolve it, close it as informative, or dismiss it, duplicates included), Kit resolves the report’s PagerDuty incident. Moves between closed statuses, such as Resolved to Fix Verified, send nothing. Once the incident is resolved, in Kit or in PagerDuty, the report’s next event opens a new incident, for example when a closed report is reopened and pages again.
Setting Up the Webhook
- Copy the Webhook URL shown on the PagerDuty settings page
- In PagerDuty, go to Integrations > Generic Webhooks (v3)
- Create a new webhook subscription with your Kit URL
- Select events:
incident.acknowledgedandincident.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 |
| A later event didn’t page | The report already has an open incident | Find the event in that incident’s alert log in PagerDuty |
| Pages reach no one | They match no route, and the catch-all suppresses them | Point the orchestration’s catch-all route at your triage service |
| A page still went to the previous team | The incident opened before the component changed | The report’s next page opens a new incident in the new component’s service |
| 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