Skip to main content
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": "[email protected]",
  "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
MethodEndpointDescription
GET/Check connection status
POST/Connect with API token
PATCH/Rotate API token
DELETE/Disconnect PagerDuty
POST/oauth/loginInitiate OAuth flow
GET/oauth/callbackOAuth callback handler
POST/webhook/{user_id}Receive V3 webhooks
GET/webhook-urlGet webhook URL
For detailed PagerDuty API documentation, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us