> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcalmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PagerDuty

> Connect Calmo to PagerDuty for comprehensive incident management, escalation, and on-call coordination through AI assistance

# PagerDuty Integration

Connect Calmo to your PagerDuty account to enable comprehensive incident management, escalation coordination, and on-call optimization through AI assistance. This integration provides access to **specialized tools** across multiple categories for complete incident response workflows.

## Overview & Value Proposition

The PagerDuty integration transforms how your team handles incident management and on-call operations by providing:

* **Intelligent Incident Analysis** - AI-powered investigation of incidents with automatic context gathering
* **Smart Escalation Management** - Automated escalation policy optimization and routing decisions
* **On-Call Intelligence** - Intelligent scheduling analysis and workload distribution insights
* **Service Health Monitoring** - Comprehensive service status tracking and dependency analysis
* **Incident Response Automation** - Streamlined workflows from detection to resolution
* **Historical Pattern Recognition** - Learning from past incidents to prevent future occurrences

## Key Capabilities

When connected, Calmo gains access to **PagerDuty tools** across multiple categories:

| Category                  | Capability                                     |
| ------------------------- | ---------------------------------------------- |
| **Incident Management**   | Create, update, resolve, and analyze incidents |
| **Service Monitoring**    | Monitor service health and dependencies        |
| **Escalation Policies**   | Manage and optimize escalation workflows       |
| **On-Call Scheduling**    | Coordinate schedules and coverage analysis     |
| **User Management**       | Team coordination and notification management  |
| **Analytics & Reporting** | Historical analysis and performance metrics    |

## Prerequisites

* PagerDuty account with appropriate access permissions
* Admin or manager access to generate API tokens
* Calmo account with team or personal workspace

## Setup Process

### Step 1: Generate PagerDuty API Token

**Create REST API Key:**

1. Log in to your [PagerDuty account](https://app.pagerduty.com)
2. Navigate to **Configuration** → **API Access**
3. Click **Create New API Key**
4. Configure API key settings:
   * **Description**: "Calmo Integration"
   * **Role**: Select appropriate access level

**Recommended Access Levels:**

| Access Level       | Capabilities                           | Use Cases                            |
| ------------------ | -------------------------------------- | ------------------------------------ |
| **Read-Only User** | View incidents, services, schedules    | Basic monitoring and analysis        |
| **Observer**       | Read incidents, limited write access   | Incident investigation with updates  |
| **Responder**      | Full incident management               | Complete incident response workflows |
| **Manager/Admin**  | All operations including configuration | Full integration capabilities        |

5. Click **Create Key**
6. Copy the generated API key immediately

### Step 2: Connect to Calmo

1. Navigate to **Integrations** in your Calmo dashboard
2. Click **PagerDuty** integration
3. Enter your **API Token**
4. Configure tool permissions:
   * ✅ **Read-only operations** enabled by default
   * ❌ **Write operations** disabled for safety
5. Complete the connection

## Tool Categories & Configuration

### 🚨 Incident Management (Mixed Safety)

**Default: Read operations enabled** - Core incident response capabilities

**Read Operations (✅ Enabled by default):**

* **List Incidents** - Query incidents with filtering and status tracking
* **Get Incident Details** - Retrieve comprehensive incident information
* **Get Incident Timeline** - Access complete incident response history
* **List Incident Notes** - View all incident communication and updates

**Write Operations (⚠️ Disabled by default):**

* **Create Incident** - Trigger new incidents programmatically
* **Update Incident** - Modify incident status, priority, and assignments
* **Resolve Incident** - Close incidents with resolution details
* **Add Incident Note** - Add contextual information to incidents

*Use Cases: Incident investigation, response coordination, status tracking, post-mortem analysis*

### 🔧 Service Management (Safe)

**Default: Enabled** - Service health and dependency monitoring

* **List Services** - Discover all monitored services and their configurations
* **Get Service Details** - Retrieve service metadata and health status
* **List Service Dependencies** - Map service relationships and dependencies
* **Get Service Metrics** - Access service performance and availability data

*Use Cases: Service discovery, dependency analysis, health monitoring, capacity planning*

### 📈 Escalation Policies (Mixed Safety)

**Default: Read-only enabled** - Escalation workflow management

**Read Operations (✅ Enabled by default):**

* **List Escalation Policies** - View all escalation workflows and rules
* **Get Escalation Policy Details** - Detailed policy configuration and routing

**Write Operations (⚠️ Disabled by default):**

* **Create Escalation Policy** - Define new escalation workflows
* **Update Escalation Policy** - Modify existing escalation rules

*Use Cases: Escalation optimization, policy analysis, workflow design, coverage planning*

### 📅 On-Call Scheduling (Mixed Safety)

**Default: Read operations enabled** - Schedule coordination and management

**Read Operations (✅ Enabled by default):**

* **List Schedules** - View all on-call schedules and rotations
* **Get Schedule Details** - Detailed schedule configuration and coverage
* **List On-Call Users** - Current and upcoming on-call assignments
* **Get Schedule Overrides** - Temporary schedule modifications

**Write Operations (⚠️ Disabled by default):**

* **Create Schedule Override** - Temporary schedule adjustments
* **Update Schedule** - Modify schedule configuration and rotations

*Use Cases: Coverage analysis, schedule optimization, on-call coordination, workload distribution*

### 👥 User Management (Safe)

**Default: Enabled** - Team coordination and communication

* **List Users** - Directory of all PagerDuty users and their roles
* **Get User Details** - Detailed user profiles and contact information
* **List User Contact Methods** - Available communication channels per user
* **Get User On-Call Status** - Current on-call assignments and availability

*Use Cases: Team coordination, contact management, escalation routing, availability tracking*

### 📊 Analytics & Reporting (Safe)

**Default: Enabled** - Performance analysis and insights

* **Get Analytics Data** - Historical incident and response metrics
* **List Log Entries** - Comprehensive audit trail of all activities
* **Get Service Metrics** - Service-level performance indicators
* **Generate Reports** - Custom reporting on incidents and response times

*Use Cases: Performance analysis, trend identification, team optimization, compliance reporting*

## Team vs Personal Configuration

### Team/Organization Setup

* Organization-wide incident response coordination
* Shared escalation policies and schedule management
* Team-level analytics and performance tracking
* Administrators control incident creation and modification permissions

### Personal Setup

* Individual on-call schedule management
* Personal incident investigation and analysis
* Private analytics and performance insights
* Full control over enabled tool capabilities

## Security & Best Practices

### ⚠️ Safety Recommendations

1. **Read-First Approach** - Begin with read-only operations, add write access gradually
2. **Token Management** - Regularly rotate API tokens according to security policies
3. **Scope Limitation** - Use minimal required access level for integration needs
4. **Incident Hygiene** - Establish clear policies for AI-assisted incident creation
5. **Escalation Testing** - Regular testing of escalation policies and workflows

### 🔒 Permission Levels

| Risk Level | Operations                          | Recommendation                |
| ---------- | ----------------------------------- | ----------------------------- |
| **Low**    | View incidents, services, schedules | ✅ Safe to enable              |
| **Medium** | Update incidents, add notes         | ⚠️ Enable with review         |
| **High**   | Create incidents, modify policies   | ⚠️ Enable only when necessary |

## Configuration Management

### Updating PagerDuty Connection

1. Navigate to **Integrations** → **PagerDuty**
2. Click **Edit Configuration**
3. Update API token or access permissions
4. Modify tool permissions based on team requirements
5. Test connection with read-only operations
6. Save configuration changes

### Managing Multiple Teams

* Configure access to multiple PagerDuty teams and services
* Set up team-specific tool permissions and workflows
* Maintain separate escalation policies per team
* Cross-team incident correlation and analysis

## Advanced Features

### Intelligent Incident Analysis

* **Context Gathering** - Automatic collection of relevant incident data
* **Pattern Recognition** - Identification of recurring incident patterns
* **Root Cause Correlation** - Link incidents to underlying service issues
* **Impact Assessment** - Automatic evaluation of incident severity and scope

### Escalation Optimization

* **Policy Analysis** - Review and optimize escalation workflows
* **Coverage Planning** - Ensure adequate on-call coverage across teams
* **Workload Distribution** - Balance incident load across team members
* **Response Time Analysis** - Identify bottlenecks in incident response

### Service Dependency Mapping

* **Dependency Visualization** - Map complex service relationships
* **Impact Propagation** - Understand how incidents affect dependent services
* **Critical Path Analysis** - Identify mission-critical service dependencies
* **Capacity Planning** - Service growth and scaling recommendations

## Integration Workflows

### Automated Incident Response

1. **Incident Detection** - Automatic monitoring of PagerDuty incident feeds
2. **Context Enrichment** - Gather relevant service and historical data
3. **Impact Analysis** - Assess incident scope and potential effects
4. **Escalation Intelligence** - Smart routing and escalation recommendations
5. **Resolution Tracking** - Monitor incident resolution progress

### Proactive Management

* **Schedule Optimization** - Analysis and recommendations for on-call schedules
* **Policy Enhancement** - Suggestions for improving escalation policies
* **Performance Monitoring** - Track team and service performance metrics
* **Predictive Analysis** - Identify potential issues before they become incidents

## Troubleshooting

### Common Issues

**Authentication Failed**

* Verify API token is correct and hasn't expired
* Check that token hasn't been revoked or deactivated
* Ensure proper access level for enabled tools

**Permission Denied**

* Review API token access level and permissions
* Check team membership for target services and escalation policies
* Verify organization-level access restrictions

**Rate Limiting**

* PagerDuty enforces API rate limits (varies by plan)
* Monitor API usage in PagerDuty account settings
* Consider upgrading PagerDuty plan for higher limits

**Service Not Found**

* Verify service names and IDs are correct
* Check that services exist and are accessible with current token
* Ensure proper team membership for private services

### Getting Help

1. **Test Connection** - Use connection test feature in integration settings
2. **Update Token** - Regenerate API token with appropriate access level
3. **Contact Support** - Reach out to [support@getcalmo.com](mailto:support@getcalmo.com) for assistance

## Data Types & Analysis

### Incident Data

* **Incident Metadata** - Title, description, severity, status, timestamps
* **Assignment Information** - Current assignees and escalation history
* **Response Timeline** - Complete incident lifecycle tracking
* **Resolution Details** - Actions taken and final resolution information

### Service Data

* **Service Configuration** - Service settings and integration details
* **Health Status** - Current operational status and availability
* **Dependency Mapping** - Service relationships and impact analysis
* **Performance Metrics** - Response times and error rates

### Team Data

* **User Profiles** - Team member information and contact details
* **Schedule Information** - On-call rotations and coverage patterns
* **Escalation Policies** - Workflow definitions and routing rules
* **Performance Analytics** - Response times and workload distribution

## PagerDuty Webhooks

Enhance your PagerDuty integration with real-time notifications that automatically create issues in Calmo when incidents occur. This provides seamless incident-to-issue tracking for complete workflow automation.

### Overview & Benefits

PagerDuty webhooks transform how your team handles incident notifications by providing:

* **Automatic Issue Creation** - Incidents become trackable issues in Calmo instantly
* **Real-time Synchronization** - Status updates flow bidirectionally between systems
* **Contextual Integration** - Issues include full incident metadata and timeline
* **Team Collaboration** - Shared visibility across personal and team contexts
* **Enterprise Security** - Cryptographic signature validation for secure data transfer

### Webhook Capabilities

When configured, PagerDuty webhooks provide comprehensive incident lifecycle tracking:

| Event Category       | PagerDuty Events                                                                                    | Calmo Action                                         |
| -------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Issue Creation**   | `incident.triggered`, `incident.escalated`, `incident.responder.added`, `incident.priority_updated` | Creates new issues with appropriate severity mapping |
| **Issue Resolution** | `incident.resolved`, `incident.acknowledged`                                                        | Marks existing issues as resolved or acknowledged    |
| **Issue Updates**    | `incident.annotated`, `incident.delegated`, `incident.reassigned`, `incident.responder.replied`     | Updates issue metadata and timeline                  |
| **Issue Reopening**  | `incident.reopened`, `incident.unacknowledged`                                                      | Reopens previously resolved issues                   |

### Setup Process

#### Step 1: Generate Webhook URL in Calmo

1. Navigate to **Integrations** → **PagerDuty** in your Calmo dashboard
2. Ensure your PagerDuty integration is active and connected
3. In the **Webhook Management** section, click **Generate Webhook**
4. Copy the generated webhook URL securely

#### Step 2: Create PagerDuty V3 Webhook Subscription

1. **Access PagerDuty Webhooks:**
   * Log in to [PagerDuty](https://app.pagerduty.com)
   * Navigate to **Integrations** → **Generic Webhooks**

2. **Create Webhook Subscription:**
   * Click **"Add Webhook Subscription"**
   * Select **"V3 Webhook Subscription"**
   * Enter your Calmo webhook URL
   * Set description: **"Calmo Integration Webhook"**
   * Choose scope: **Service** or **Account** based on requirements

3. **Configure Event Types:**
   Select events based on your workflow needs:
   * **Essential Events**: `incident.triggered`, `incident.resolved`, `incident.acknowledged`
   * **Extended Events**: `incident.escalated`, `incident.responder.added`, `incident.priority_updated`
   * **Advanced Events**: All remaining incident events for complete tracking

4. **Apply Filters (Optional):**
   * **Service Filter**: Limit to specific services
   * **Team Filter**: Restrict to particular teams
   * **Leave empty**: Receive all account incidents

5. **Save and Copy Signing Secret:**
   * Click **"Save"** to create the subscription
   * **Important**: Copy the signing secret immediately (shown only once)

#### Step 3: Configure Signature Validation (Recommended)

1. Return to Calmo's **Webhook Management** section
2. Click **"Add Signing Secret"** next to your webhook
3. Paste the PagerDuty signing secret
4. Complete the validation wizard to verify security setup

##### How to Get Your PagerDuty Webhook Signing Secret

When setting up webhooks in PagerDuty, follow these steps to obtain your signing secret:

1. **Create a new webhook subscription** in your PagerDuty account
2. **During setup, PagerDuty will display a signing secret** - copy it immediately
3. **You won't be able to see it again** after leaving the page
4. **Paste the secret into Calmo** so we can verify incoming webhooks

> ⚠️ **Important**: If you didn't copy the secret during initial setup, you'll need to create a new webhook subscription to get a new secret.

#### Step 4: Test Integration

1. Use Calmo's **"Test Endpoint"** button for connectivity verification
2. Trigger a test incident in PagerDuty
3. Verify the issue appears in your Calmo dashboard
4. Confirm resolution workflows update correctly

### Security & Best Practices

#### Enterprise Security Features

* **HMAC-SHA256 Encryption**: Industry-standard cryptographic signature validation
* **Timing-Safe Comparison**: Protection against timing attack vulnerabilities
* **Secure Secret Storage**: Encrypted webhook secrets with per-webhook isolation
* **Request Validation**: Comprehensive payload integrity verification

#### Configuration Best Practices

1. **Always Enable Signature Validation** - Ensures webhook authenticity and prevents spoofing
2. **Use Service Filters** - Reduce noise by targeting specific services
3. **Monitor Webhook Status** - Regular testing and status verification
4. **Secure Secret Management** - Treat signing secrets as sensitive credentials
5. **Test Thoroughly** - Validate complete incident lifecycle workflows

### Priority and Severity Mapping

PagerDuty incident priorities automatically map to appropriate Calmo severity levels:

| PagerDuty Priority         | Calmo Severity | Visual Indicator              |
| -------------------------- | -------------- | ----------------------------- |
| **P1, P2, Critical, High** | Critical       | Red alert indicators          |
| **P3, Medium**             | Warning        | Yellow warning indicators     |
| **P4, P5, Low, Info**      | Info           | Blue informational indicators |
| **Unknown/Unset**          | Medium         | Default yellow indicators     |

This mapping ensures consistent incident classification and appropriate response prioritization across both systems.

### Team vs Personal Webhooks

#### Personal Webhook Configuration

* **Scope**: Individual user context
* **Visibility**: Private to webhook creator
* **Use Case**: Personal on-call responsibilities and individual incident tracking
* **Setup**: Generate webhook without organization context

#### Team Webhook Configuration

* **Scope**: Organization/team context
* **Visibility**: Shared across all team members
* **Use Case**: Collaborative incident response and team coordination
* **Setup**: Generate webhook with organization ID parameter

### Advanced Integration Scenarios

#### Multi-Service Monitoring

* Configure separate webhooks for different service categories
* Use PagerDuty service filters for targeted incident routing
* Implement team-specific webhooks for service ownership models

#### Escalation Policy Integration

* Map PagerDuty escalation events to Calmo issue assignments
* Track escalation patterns for team performance analysis
* Automate response coordination through combined incident and issue workflows

#### Analytics and Reporting

* Leverage webhook data for incident trend analysis
* Combine PagerDuty API tools with webhook automation
* Generate custom reports on incident response effectiveness

### Troubleshooting

#### Common Issues and Solutions

**Webhook Not Receiving Events:**

* Verify webhook URL is correctly configured in PagerDuty
* Check PagerDuty integration status in Calmo (must be active)
* Confirm selected event types match your testing scenarios
* Use Calmo's "Test Endpoint" feature for connectivity verification

**Signature Validation Failures:**

* Ensure signing secret was copied correctly during PagerDuty setup
* Verify the secret was pasted without extra whitespace or characters
* Re-run the validation wizard if verification fails
* Check webhook logs for specific signature mismatch details

**Issues Not Created in Expected Context:**

* Verify organization ID parameter for team vs personal webhooks
* Confirm team membership for organization-scoped webhooks
* Check webhook generation logs for context configuration

**Missing Issue Updates:**

* Ensure comprehensive event type selection in PagerDuty
* Verify incident IDs match between PagerDuty events and Calmo issues
* Check for webhook rate limiting or delivery failures

#### Advanced Debugging

Access webhook logs and metrics through Calmo's integration management interface:

* **Connectivity Tests**: Real-time endpoint verification
* **Event Logs**: Complete webhook delivery history
* **Signature Validation Logs**: Security verification audit trail
* **Issue Creation Tracking**: End-to-end workflow monitoring

For persistent issues or advanced configuration requirements, contact support at [support@getcalmo.com](mailto:support@getcalmo.com).

***

The PagerDuty integration provides comprehensive incident management and on-call coordination capabilities, enabling your team to respond to incidents efficiently and optimize operational workflows through AI-powered assistance while maintaining strict operational controls.

***

*For additional help with PagerDuty integration, contact our support team at [support@getcalmo.com](mailto:support@getcalmo.com).*