Skip to content
StartupKit
EN

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

  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)

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

  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 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.

  1. In PagerDuty, go to Event Orchestration (under Configuration > Events & Routing, or AIOps on some accounts) and create an orchestration
  2. Open its Integrations and copy the integration key
  3. In Kit, paste it as the Integration Key on VDP > Settings > PagerDuty
  4. 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
  5. 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.

  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. 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

  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
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

Type to search...