PagerDuty Integration

Connect PagerDuty to enable agents to access incidents, on-call schedules, and alert data during investigations.

Capabilities

Once connected, agents can:

Capability	Description
View Incidents	Access PagerDuty incident details and timelines
On-Call Schedules	Find who is currently on call
Alert Data	Retrieve alert details and trigger information
Service Status	Check service health and escalation policies
Incident History	Search past incidents for similar patterns
Alert Source Webhooks	Receive PagerDuty incident events (triggered, acknowledged, resolved) via Generic Webhook v3, with optional HMAC-SHA256 signature verification

Prerequisites

• A PagerDuty account with API access
• A REST API Key (General Access or User Token)
• Read permissions for incidents, services, and schedules

Setup

1

Get Your API Key

1. Log in to your PagerDuty account
2. Navigate to Integrations → Developer Tools → API Access Keys
3. Click Create New API Key
4. Enter a description (e.g., "Autoheal Integration")
5. Select Read-only API Key if available
6. Copy the generated API key

2

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click PagerDuty
3. Enter a name (e.g., "Production PagerDuty")

3

Configure Credentials

Enter the following:

• API Key: Your PagerDuty REST API key

4

Test and Save

Click Test Connection to check the connection. Then click Save.

API Key Types

PagerDuty supports two types of REST API keys:

Type	Scope	Recommended
General Access REST API Key	Account-wide access	Yes (for org-level visibility)
User Token REST API Key	Scoped to a specific user	Yes (for limited access)

tip

Use a General Access REST API Key for the broadest visibility into incidents and services. If you need to limit scope, use a User Token REST API Key tied to a service account.

Required Permissions

The API key should have at least these permissions:

Permission	Why It's Needed
Read access to Incidents	View incident details and timelines
Read access to Services	Check service status
Read access to Schedules	Get on-call information
Read access to Users	Identify responders

Example Queries

Once connected, you can ask an agent questions like:

Who is currently on call for the payments team?

Show me all open PagerDuty incidents

What incidents were triggered for the checkout service this week?

Get the timeline for PagerDuty incident #12345

Alert Source Setup

PagerDuty can act as an alert source by forwarding incident events to Autoheal via a Generic Webhook v3. Autoheal ingests triggered, acknowledged, and resolved events and maps them to alerts on the Alerts page.

Configure PagerDuty as an Alert Source

1

Enable the Webhook in Autoheal

1. Open your PagerDuty integration in Autoheal
2. Scroll to the Alert Source section
3. Enable the webhook. Then copy the Webhook URL

2

Create a Generic Webhook v3 in PagerDuty

1. In PagerDuty, go to Integrations → Generic Webhooks (v3). Then click New Webhook
2. Paste the Webhook URL from Autoheal into the URL field
3. Set Scope Type to Service (or Team). Then select the services/teams whose incidents you want to forward
4. Under Event Subscriptions, select at least incident.triggered. Also enable incident.acknowledged and incident.resolved if you want status updates
5. Click Add Webhook. PagerDuty will display a one-time Signing Secret. Copy it immediately

3

Paste the Signing Secret (Optional but Recommended)

1. Back in Autoheal, paste the Signing Secret into the Signing Secret field of the PagerDuty integration
2. When the Signing Secret is set, Autoheal verifies the HMAC-SHA256 signature on every delivery. If the signature is missing or invalid, Autoheal rejects the request with 401

4

Test the Integration

Trigger a test incident on one of the scoped services (for example via pd-test or by manually creating an incident). The alert should appear on Autoheal's Alerts page within a few seconds.

note

PagerDuty signs webhook deliveries with HMAC-SHA256 using the format v1=<hex> in the x-pagerduty-signature header. The signing secret is shown only once when the webhook is created. If you lose it, regenerate the webhook in PagerDuty. Then update the value in Autoheal.

tip

The webhook URL already contains a unique per-integration secret, so only a caller with that exact URL can reach your endpoint. Adding the Signing Secret provides a second line of defence by verifying the payload signature.

Troubleshooting

401 Unauthorized Error

• Check that the API key is correct and has not been revoked
• Check that the API key has the required permissions
• Check that the key is a REST API key (not an Events API key)

No Incidents Found

• Check that the time range includes active incidents
• Check that the API key has access to the relevant services
• Check that there are incidents matching your query criteria

Rate Limiting

• PagerDuty enforces API rate limits
• Reduce query frequency if you encounter 429 errors
• Use more specific queries to reduce the number of API calls

Webhook Alerts Not Appearing in Autoheal

• Check that the webhook URL pasted into PagerDuty matches the one shown in Autoheal exactly
• Check that the webhook's Scope covers the service(s) whose incidents you want forwarded
• Check that at least incident.triggered is selected in Event Subscriptions
• Check that the webhook is enabled in the Autoheal integration settings

Webhook Returns 401 (Signature Verification Failed)

• If you configured a Signing Secret in Autoheal, confirm it matches the value PagerDuty showed when the webhook was created
• PagerDuty signing secrets are shown only once. If you are unsure, regenerate the webhook. Then update the secret in Autoheal
• To disable signature verification, clear the Signing Secret field in Autoheal