Skip to main content

PagerDuty

PagerDuty is an incident management platform that helps teams respond to and resolve critical incidents in real-time. It provides on-call scheduling, alerting, escalation management, and analytics to ensure the right people are notified at the right time when incidents occur. Teams use PagerDuty to manage their incident response workflow, coordinate on-call rotations, and improve their overall incident resolution times.

Authentication Types​

PagerDuty supports 2 authentication methods:

  • OAuth 2.0 - Secure, app-based authentication with granular permission control.

    • Pros: Most secure, per-user tracking, granular scope control, production-ready, better audit trail
    • Cons: Requires admin privileges to set up, more complex initial setup (~5-10 min)
    • Best for: Production deployments, multi-user scenarios, compliance requirements, marketplace integrations

  • API Key - Simple, personal API token for quick integration.

    • Pros: Very simple setup, works immediately, no app registration needed
    • Cons: Single shared credential, full account access, less granular permissions, weaker audit trail
    • Best for: Personal use, testing, quick prototypes, single-user scenarios, development environments

Setting up OAuth 2.0​

OAuth 2.0 is the recommended authentication method for production use. You'll need administrator privileges in your PagerDuty account.

1. Access App Registration​

  1. Log in to your PagerDuty account as an administrator

  2. Navigate to Integrations in the top navigation bar

  3. Under Developer Tools column, click App Registration

tip

Only account administrators and owners can create OAuth applications. If you don't see the App Registration option, contact your PagerDuty administrator.

2. Register a New App​

  1. Click Register an App or Create New App

  2. Select OAuth 2.0 as the app type

  3. Fill in the app details:

    • App Name: Give it a descriptive name (e.g., "Webrix AI Integration")
    • Brief Description: Describe what the app does
    • Category: Select "Incident Management" or "Developer Tools"
    • Redirect URL: Copy the OAuth redirect URL from Webrix and paste it here

  4. Click Save or Next

3. Configure OAuth Scopes​

  1. On the Scopes or Permissions page, select the scopes your integration needs:

    Recommended minimum scopes for basic functionality:

    • incidents.read - View incidents
    • incidents.write - Acknowledge and resolve incidents
    • services.read - View services
    • users.read - View users
    • oncalls.read - View on-call schedules
    • schedules.read - View schedules

    Additional scopes for advanced features:

    • services.write - Modify service configurations
    • schedules.write - Create schedule overrides
    • escalation_policies.read - View escalation policies
    • teams.read - View teams
    • analytics.read - Access incident analytics
    • priorities.read - View incident priorities
    • abilities.read - Discover account features

  2. Click Save

4. Get Client Credentials​

  1. After saving, you'll see the Client ID displayed

  2. Click Show or Generate Client Secret to reveal the Client Secret

  3. Copy both the Client ID and Client Secret

warning

Keep your Client Secret secure! It's shown only once. Never share it publicly or commit it to version control. If you lose it, you'll need to regenerate it, which will break existing connections.

5. Configure in Webrix​

  1. In Webrix, navigate to Integrations → Add Integration → Built-in

  2. Select PagerDuty and click Use

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID in the Client ID field

  5. Paste your Client Secret in the Client Secret field

  6. Review and select the Scopes you granted in PagerDuty (they should match)

  7. Click Save Changes

6. Test the Connection​

  1. After saving, click Connect to initiate the OAuth flow

  2. You'll be redirected to PagerDuty to authorize the app

  3. Review the permissions requested and click Authorize or Allow

  4. You'll be redirected back to Webrix with a successful connection

  5. The integration is now ready to use

Setting up API Key​

API Key authentication provides quick setup but uses a shared credential with full account access. Requires account administrator privileges.

1. Generate an API Key​

  1. Log in to your PagerDuty account as an administrator

  2. Navigate to Configuration → API Access in the menu

    (Alternative path: Click your profile icon → API Access Keys)

  3. Click Create New API Key

  4. Fill in the details:

    • Description: Give it a descriptive name (e.g., "Webrix Integration")
    • Read Only: Leave unchecked (we need write access for incident management)

  5. Click Create Key

  6. IMPORTANT: Copy the API key value immediately - it will only be shown once

caution

API Keys have full administrative access to your PagerDuty account. Store them securely, rotate them regularly (every 90 days recommended), and never commit them to source control or share them publicly.

2. Configure in Webrix​

  1. In Webrix, navigate to Integrations → Add Integration → Built-in

  2. Select PagerDuty and click Use

  3. Under Authentication Type, select API Key

  4. Paste your API Key in the token field

  5. Click Save Changes

3. Test the Connection​

  1. After saving, click Connect to test the connection

  2. If successful, you'll see a confirmation message

  3. The integration is now ready to use

Available Operations​

The PagerDuty connector provides 23 tools organized into 6 categories:

Incidents Management (7 tools)​

Core incident response operations:

  • List Incidents - Query incidents with flexible filters (status, urgency, date range, service, team, user)
  • Get Incident - Retrieve detailed incident information including timeline
  • Create Incident - Manually create a new incident for a service
  • Update Incident - Modify incident properties (title, urgency, priority, status, escalation)
  • Acknowledge Incident - Acknowledge one or more incidents (bulk operation supported)
  • Resolve Incident - Resolve one or more incidents (bulk operation supported)
  • List Incident Alerts - Get all alerts associated with an incident

Services (3 tools)​

Service catalog and configuration:

  • List Services - Browse services with filters (team, query, include escalation policies)
  • Get Service - Retrieve detailed service configuration
  • Update Service - Modify service settings (name, description, escalation policy, timeouts)

On-Calls & Schedules (4 tools)​

Managing who's on-call:

  • List On-Calls - Get current on-call users (filter by schedule, escalation policy, user, time)
  • List Schedules - Browse all on-call schedules
  • Get Schedule - Retrieve schedule details with coverage for a date range
  • Create Schedule Override - Create temporary schedule overrides for shift swaps or time off

Users & Teams (4 tools)​

User and team management:

  • List Users - Browse users with filters (team, query, include contact methods)
  • Get User - Retrieve user details including contact methods and notification rules
  • List Teams - Browse all teams
  • Get Team - Retrieve team details

Escalation Policies (2 tools)​

Escalation configuration:

  • List Escalation Policies - Browse escalation policies (filter by team, user, query)
  • Get Escalation Policy - Retrieve policy details with all escalation rules and levels

Analytics & Abilities (3 tools)​

Reporting and feature discovery:

  • Get Abilities - List enabled features for the account
  • Get Analytics Metrics - Retrieve incident analytics (MTTA, MTTR, incident counts, trends)
  • List Priorities - Get configured incident priorities (P1, P2, P3, etc.)

Common Use Cases​

Incident Response Workflow​

List Incidents (filter: status=triggered)
→ Get Incident (review details)
→ Acknowledge Incident
→ (investigate and fix)
→ Resolve Incident

Check Current On-Call​

List On-Calls (filter by schedule/escalation policy)
→ Get User (get contact details for on-call person)

Service Health Check​

List Services
→ Get Service (check configuration)
→ List Incidents (filter by service)
→ Get Analytics Metrics (check MTTA/MTTR for service)

Schedule Management​

List Schedules
→ Get Schedule (view coverage for date range)
→ Create Schedule Override (handle time off or shift swap)

Incident Analysis​

List Incidents (filter by date range)
→ Get Incident (examine details)
→ List Incident Alerts (see all triggering alerts)
→ Get Analytics Metrics (measure response times)

User Management​

List Users
→ Get User (review notification rules)
→ List On-Calls (check user's on-call schedule)

Troubleshooting​

"Invalid API key" or "Access denied" error​

Cause: The API key is incorrect, expired, has been revoked, or lacks necessary permissions.

Solution:

  1. Verify you copied the complete API key value (they're quite long)
  2. Check that the API key hasn't been deactivated in PagerDuty Configuration → API Access
  3. Ensure the API key is not "Read Only" (we need write access for incident operations)
  4. Generate a new API key and update Webrix
  5. Test the connection after updating

"Insufficient permissions" error (OAuth)​

Cause: The OAuth application doesn't have the required scopes granted for the operation.

Solution:

  1. Go to your OAuth app in PagerDuty App Registration
  2. Review the granted scopes - ensure they match what's needed for your operations
  3. Add any missing scopes (e.g., incidents.write for acknowledging incidents)
  4. Save the changes in PagerDuty
  5. Reconnect in Webrix to get a new token with updated scopes
  6. The error should include which scope is missing - use that to identify what to add

"From header required" error​

Cause: Operations that modify incident state (acknowledge, resolve, create, update) require a From header with the email of the user performing the action for audit purposes.

Solution:

  1. When using tools like Acknowledge Incident, Resolve Incident, Create Incident, or Update Incident, ensure you provide the from_email parameter
  2. The email must belong to a valid PagerDuty user in your account
  3. This is required by PagerDuty's API for audit trail purposes
  4. Example: from_email: "[email protected]"

Rate limit errors (429 status)​

Cause: PagerDuty enforces rate limits of 960 requests per minute per API key or OAuth token.

Solution:

  1. Implement exponential backoff in your retry logic
  2. Wait a minute before retrying after hitting the limit
  3. Use bulk operations where possible (e.g., acknowledge/resolve multiple incidents at once)
  4. Reduce the frequency of API calls in your workflows
  5. Consider caching results that don't change frequently (schedules, services, escalation policies)
  6. Contact PagerDuty support if you consistently hit limits and need an increase

"Incident not found" or "Service not found" error​

Cause: The resource ID doesn't exist, has been deleted, or you don't have permission to access it.

Solution:

  1. Verify the ID is correct - use List operations to find valid IDs
  2. Check that the resource hasn't been deleted
  3. Ensure your OAuth scopes or API key has access to the resource
  4. For team-scoped resources, verify your user has access to the relevant team
  5. Try using List Incidents or List Services to confirm the resource exists

Schedule gaps or incorrect on-call assignments​

Cause: Schedule configuration issues, missing layers, or incorrect timezone handling.

Solution:

  1. Use Get Schedule to review schedule layers and coverage
  2. Check the time_zone parameter - ensure it matches your expectations
  3. Verify schedule layers don't have gaps in coverage
  4. Check for conflicting overrides that might affect coverage
  5. Review schedule restrictions (daily/weekly time restrictions)
  6. Ensure users in the schedule are active and have valid contact methods

OAuth redirect URI mismatch error​

Cause: The redirect URL in your PagerDuty app doesn't match the one being used during the OAuth flow.

Solution:

  1. Copy the exact redirect URI from Webrix
  2. Go to your PagerDuty app in App Registration
  3. Ensure the redirect URI is added exactly as shown (including https:// and any trailing slashes)
  4. Save the changes and try connecting again
  5. If the issue persists, try removing and re-adding the redirect URI

Cannot create incidents - "Service not found" error​

Cause: The service ID is invalid or your account doesn't have access to the service.

Solution:

  1. Use List Services to get valid service IDs
  2. Ensure the service hasn't been deleted
  3. Verify your OAuth scopes include services.read
  4. Check that your user has access to the team that owns the service
  5. Copy the service ID from the List Services response (usually starts with "P")

Best Practices​

Authentication​

  1. Use OAuth for production - OAuth provides better security, audit trails, and per-user tracking
  2. Grant minimal scopes - Only request the OAuth scopes you actually need (principle of least privilege)
  3. Rotate API keys regularly - If using API keys, rotate them every 90 days
  4. Store credentials securely - Never commit credentials to version control or share them publicly
  5. Monitor for unauthorized access - Regularly review API access in PagerDuty's audit logs

Incident Management​

  1. Use bulk operations - Acknowledge or resolve multiple incidents at once using arrays of IDs
  2. Always provide from_email - Include the user's email for proper audit trails
  3. Filter incidents effectively - Use status, urgency, and date filters to find relevant incidents quickly
  4. Check incident alerts - Use List Incident Alerts to understand root causes
  5. Set appropriate priorities - Use List Priorities to find valid priority IDs, then assign them consistently

On-Call Management​

  1. Plan overrides in advance - Create schedule overrides early for known time off or shift swaps
  2. Verify schedule coverage - Use Get Schedule with date ranges to ensure no gaps
  3. Check timezone handling - Always specify time_zone parameter to avoid confusion
  4. Document on-call procedures - Keep escalation policies and schedules well-documented
  5. Test escalations - Periodically verify escalation policies work as expected

Performance & Reliability​

  1. Implement retry logic - Use exponential backoff for failed requests
  2. Handle rate limits - Monitor for 429 errors and implement proper backoff
  3. Cache stable data - Cache services, escalation policies, schedules that don't change often
  4. Use pagination - Don't try to fetch all records at once; use limit and offset
  5. Monitor integration health - Set up alerts for integration failures

Analytics & Reporting​

  1. Track MTTA and MTTR - Regularly review incident response metrics
  2. Segment by service/team - Use filters to compare performance across services
  3. Set baselines and SLOs - Establish target response times and measure against them
  4. Review trends - Use aggregate_unit (day/week/month) to identify patterns
  5. Act on insights - Use analytics to identify areas for improvement in your incident response

Service Configuration​

  1. Configure acknowledgement timeouts - Set reasonable timeouts to re-notify if incidents aren't acknowledged
  2. Set auto-resolve timeouts carefully - Only use auto-resolve when appropriate for your services
  3. Map services to teams - Assign services to teams for better organization and filtering
  4. Review escalation policies - Ensure escalation policies match your on-call rotations
  5. Test service integrations - Verify monitoring tools can create incidents successfully

Security Considerations​

  • Incident operations are destructive - Acknowledging, resolving, and creating incidents affect production systems
  • API keys have full account access - Treat them as highly sensitive credentials
  • OAuth scopes should follow least privilege - Only grant the minimum scopes needed
  • Audit trails are important - The from_email parameter enables proper audit logging
  • Rate limits protect the platform - Don't attempt to circumvent rate limits
  • Regular access reviews - Periodically audit who has API access and OAuth connections
  • Incident data is sensitive - May contain details about outages, customer impact, and system vulnerabilities

Rate Limits​

PagerDuty enforces the following rate limits:

  • 960 requests per minute per API key or OAuth token
  • Rate limit headers are included in responses:
    • X-Rate-Limit-Limit - Your rate limit ceiling
    • X-Rate-Limit-Remaining - Requests remaining in current period
    • X-Rate-Limit-Reset - Time when the rate limit resets (Unix timestamp)

When you exceed the rate limit, you'll receive a 429 status code. Implement exponential backoff and respect the rate limit headers to avoid disruptions.

API Version​

The PagerDuty connector uses REST API v2, indicated by the header:

Accept: application/vnd.pagerduty+json;version=2

This header is automatically included in all requests. The API version is stable and widely supported.

Additional Resources​