PagerDuty Integration

Integrate PagerDuty with Aurora for incident management, on-call scheduling, and automated incident response

Connect Aurora with PagerDuty to receive incident webhooks, manage on-call rotations, and leverage AI-powered root cause analysis for faster incident resolution.

Authentication

PagerDuty supports two authentication methods:

1. API Token (Recommended for development)
2. OAuth 2.0 (Recommended for production)

Option A: API Token

1. Create API Key

   1. Go to PagerDuty
   2. Navigate to Integrations > API Access Keys
   3. Click Create New API Key
   4. Select Read or Write permissions (both work)
   5. Copy the generated token
2. Connect to Aurora

   1. In Aurora, go to Integrations > PagerDuty
   2. Paste your API token
   3. Click Connect

Option B: OAuth 2.0

1. Create OAuth App

   1. Go to PagerDuty
   2. Navigate to Integrations > Developer Mode > My Apps
   3. Click Create New App
   4. Name: Aurora
   5. Enable OAuth 2.0
   6. Redirect URL: http://localhost:5000/pagerduty/oauth/callback (for development)
   7. Copy the Client ID and Client Secret
2. Configure Environment

   Add to your .env file:

   .env

   NEXT_PUBLIC_ENABLE_PAGERDUTY_OAUTH=true
   PAGERDUTY_CLIENT_ID=your-client-id
   PAGERDUTY_CLIENT_SECRET=your-client-secret
   
3. Restart Services

   Restart Aurora to apply the OAuth configuration:

   make down && make dev
   
4. Connect via OAuth

   1. In Aurora, go to Integrations > PagerDuty
   2. Click Connect with OAuth
   3. Authorize Aurora in the PagerDuty popup

Configuration

Environment Variables

.env

# Enable OAuth (optional)
NEXT_PUBLIC_ENABLE_PAGERDUTY_OAUTH=true
PAGERDUTY_CLIENT_ID=your-client-id
PAGERDUTY_CLIENT_SECRET=your-client-secret

# For local webhook development
NGROK_URL=https://your-ngrok-url.ngrok-free.app

Webhook Setup

Receive real-time incident notifications from PagerDuty (V3 webhooks only).

Local Development Setup

1. Start Port Forwarding

   PagerDuty webhooks cannot reach localhost:5080 directly. Use ngrok:

   ngrok http 5080
   

   Copy the HTTPS URL (e.g., https://abc123.ngrok-free.app)

2. Set Environment Variable

   Add to .env:

   .env

   NGROK_URL=https://abc123.ngrok-free.app
   

   Restart Aurora services:

   make down && make dev
   
3. Get Webhook URL

   In Aurora’s PagerDuty integration page, copy your webhook URL:

   https://abc123.ngrok-free.app/pagerduty/webhook/{user_id}
   
4. Configure Webhook in PagerDuty

   1. Go to PagerDuty
   2. Navigate to Integrations > Generic Webhooks (v3) > New Webhook
   3. Paste the Aurora webhook URL
   4. Set scope to Account or specific services
   5. Subscribe to events:
      • incident.triggered
      • incident.acknowledged
      • incident.resolved
      • incident.custom_field_values.updated
   6. Click Add Webhook
   7. Send a test notification to verify

Production Setup

In production, webhooks use your production backend URL automatically. No port forwarding needed.

Webhook URL format:

https://your-aurora-domain/pagerduty/webhook/{user_id}

What Aurora Can Query

Once connected, Aurora can:

Connection Status

• Verify token validity
• View connected user info
• Check account subdomain
• View token capabilities (read/write)

API Endpoint: GET /pagerduty

Response:

{
  "connected": true,
  "displayName": "PagerDuty",
  "authType": "api_token",
  "externalUserEmail": "[e-mail]",
  "externalUserName": "John Doe",
  "accountSubdomain": "your-company",
  "capabilities": {
    "can_read_incidents": true,
    "can_write_incidents": true
  },
  "validatedAt": "2026-03-03T10:00:00Z"
}

Webhook Events (V3 Only)

• Receive real-time incident events
• Auto-create Aurora incidents
• Track incident lifecycle (triggered, acknowledged, resolved)
• Monitor custom field updates
• Correlate related incidents
• Generate AI-powered root cause analysis

Supported Events:

• incident.triggered - New incident created
• incident.acknowledged - Incident acknowledged
• incident.resolved - Incident resolved
• incident.custom_field_values.updated - Custom fields changed

Ingested Data:

• Incident ID and title
• Incident status and urgency
• Service and escalation policy info
• Assignee information
• Custom field values
• Related alerts and context

PagerDuty V1 and V2 webhooks are not supported. You must use V3 Generic Webhooks.

Troubleshooting

“PagerDuty OAuth is not enabled”

• Set NEXT_PUBLIC_ENABLE_PAGERDUTY_OAUTH=true in .env
• Restart Aurora services

“Missing OAuth credentials”

• Verify PAGERDUTY_CLIENT_ID and PAGERDUTY_CLIENT_SECRET are set
• Check for typos in environment variable names

“Unauthorized: Invalid or expired API token”

• Verify token is correct and not revoked
• Check token has required permissions (Read or Write)
• For OAuth: token may have expired, reconnect

Webhook Not Receiving Events

• Verify NGROK_URL is set correctly (local development)
• Ensure ngrok/cloudflared tunnel is running
• Check webhook URL in PagerDuty matches Aurora UI
• Confirm webhook is subscribed to correct events
• Send test notification from PagerDuty
• Check Aurora logs for webhook errors

“Account-level token” errors

• Some account-level tokens cannot access user info
• Aurora will still work, but may not show user details
• Consider using a user-level token or OAuth

API Reference

Base Path: /pagerduty

Method	Endpoint	Description
GET	/	Check connection status
POST	/	Connect with API token
PATCH	/	Rotate API token
DELETE	/	Disconnect PagerDuty
POST	/oauth/login	Initiate OAuth flow
GET	/oauth/callback	OAuth callback handler
POST	/webhook/{user_id}	Receive V3 webhooks
GET	/webhook-url	Get webhook URL

For detailed PagerDuty API documentation, see:

• PagerDuty API Reference
• PagerDuty Webhooks V3