Fast and reliable incident response isn't optional anymore—your customers expect
it.
[PagerDuty](https://developer.pagerduty.com/api-reference/f1a95bb9397ba-changelog),
with its powerful API, sits at the center of incident management, offering a
robust platform that helps teams catch and fix issues before users notice
anything wrong.

The PagerDuty API lets you build custom automations that make monitoring,
alerting, and incident response workflows smoother than ever.
[Research from PagerDuty](https://www.pagerduty.com/resources/reports/digital-operations/)
shows companies automating their incident management fix problems 70% faster.

When you combine PagerDuty's specialized APIs with a solid API management
platform, you unlock serious potential. A code-first approach gives developers
control over every step of the incident lifecycle—from detection to
resolution—while keeping everything secure and performant.

Whether you want to connect your monitoring tools, build custom dashboards, or
create smart automation workflows, getting familiar with the PagerDuty API
ecosystem is your first step toward stronger operations. This guide has all you
need to get started.

## Understanding PagerDuty API Components

When connecting to PagerDuty's incident management platform, knowing the
different API pieces helps you build effective automations. PagerDuty offers
three main API types, each handling specific parts of your incident management
workflows.

### Overview of the PagerDuty API Types

1. **REST API**: The
   [PagerDuty REST API](https://developer.pagerduty.com/docs/rest-api-overview)
   gives you complete access to manage everything in PagerDuty. Use it to handle
   incidents, users, schedules, and more through standard operations.
2. **Events API**: The
   [PagerDuty Events API](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTc3-events-api-v1)
   focuses on triggering, acknowledging, and resolving incidents in real-time.
   It's the main way to connect monitoring tools with PagerDuty.
3. **Webhooks**: PagerDuty's webhook system pushes updates to your systems as
   incidents change. This lets you build responsive automated processes that
   react immediately when something changes.

### Choosing the Right PagerDuty API for Your Needs

Your specific goals determine which PagerDuty API makes the most sense:

For managing all your PagerDuty resources, the REST API excels at:

- Creating and updating on-call schedules
- Managing user accounts and permissions
- Getting detailed incident information for reports

When you need to create incidents from monitoring tools, the Events API works
best for:

- Creating new incidents from system alerts
- Updating incidents with acknowledgments or resolutions
- Sending custom event data to PagerDuty

For instant updates about incident changes, webhooks provide:

- Immediate notifications when incidents change state
- Triggers for automated responses
- Data for live dashboards showing current incidents

These APIs work best together. You might use the Events API to create incidents,
webhooks to get real-time updates, and the REST API to manage the entire
incident lifecycle programmatically.

## Integrating the PagerDuty REST API

The PagerDuty REST API gives you programmatic control over your incident
management ecosystem. With it, you can automate everything from creating
incidents to managing schedules, forming a foundation for
[API integration platform creation](/learning-center/building-an-api-integration-platform).

### Authentication and Request Headers

Security matters when handling incident data. PagerDuty offers two main ways to
authenticate:

1. **API Access Keys**: Perfect for server-to-server connections, include your
   key in the Authorization header:  
   Authorization: Token token=YOUR_API_KEY
2. **OAuth 2.0**: For apps acting on behalf of users,
   [OAuth 2.0](https://developer.pagerduty.com/docs/app-oauth-token) provides
   better security through temporary tokens:  
   Authorization: Bearer YOUR_ACCESS_TOKEN

For more on choosing the right
[API authentication methods](/learning-center/api-authentication), consider the
security requirements of your application. To better understand which method
suits your needs, you can refer to an in-depth
[API authentication comparisons](/learning-center/top-7-api-authentication-methods-compared).

Always include these headers with requests:

```http
Accept: application/vnd.pagerduty+json;version=2
Content-Type: application/json
```

### Common Endpoints and Actions

The PagerDuty REST API has many endpoints, but these are the workhorses for most
integrations:

1. **Incidents**: Manage the incident lifecycle
   - List incidents: `GET /incidents`
   - Create an incident: `POST /incidents`
   - Update an incident: `PUT /incidents/{id}`
2. **Services**: Configure monitored services
   - List services: `GET /services`
   - Get service details: `GET /services/{id}`
   - Create a service: `POST /services`
3. **Schedules**: Manage on-call rotations
   - List schedules: `GET /schedules`
   - Get schedule details: `GET /schedules/{id}`
   - Create overrides: `POST /schedules/{id}/overrides`

When using the REST API, handle errors properly and respect
[rate limits](https://developer.pagerduty.com/docs/rest-api-rate-limits). Watch
the `X-RateLimit-Remaining` header and add retry logic with exponential backoff
for 429 responses to keep critical integrations running smoothly.

## Customizing Alerts with the PagerDuty Events API

The PagerDuty Events API connects your monitoring tools and applications to
PagerDuty's incident management system. Unlike other APIs, it has one job:
handling incident creation and updates based on real-time events.

### Introduction to the PagerDuty Events API

The Events API supports three main event types:

- **Trigger**: Creates a new incident or adds to an existing one
- **Acknowledge**: Marks an incident as being worked on
- **Resolve**: Closes an incident

These event types match the natural lifecycle of incidents, letting your
monitoring systems manage the entire incident process automatically from
detection to resolution.

### Configuration and Use Cases

The PagerDuty Events API shines when connected to monitoring systems. Common
setups include:

1. **Infrastructure monitoring**: Connect tools like
   [Nagios](https://www.nagios.org/) or [Prometheus](https://prometheus.io/) to
   trigger incidents when servers, networks, or databases have problems.
2. **Application performance monitoring**: Have
   [New Relic](https://newrelic.com/) or
   [AppDynamics](https://www.splunk.com/en_us/appdynamics-joins-splunk.html)
   create PagerDuty incidents when applications experience errors or slow down.
3. **Custom application integrations**: Add Events API calls directly in your
   applications to trigger incidents for critical errors that need immediate
   attention.

When using the Events API, you can customize incident details to give responders
rich context:

```python
payload = {
    "routing_key": "YOUR_INTEGRATION_KEY",
    "event_action": "trigger",
    "payload": {
        "summary": "Database connection pool exhausted",
        "severity": "critical",
        "source": "mysql-prod-01",
        "component": "database",
        "group": "production",
        "class": "connectivity"
    }
}
```

### Version Differences and Enhancements

PagerDuty's Events API has evolved, with the current v2 offering improvements
over v1:

1. **Better deduplication**: V2 has smarter incident deduplication based on the
   `dedup_key`.
2. **Custom event fields**: V2 supports custom fields for extra structured data.
3. **Links and images**: V2 lets you attach relevant links and images to
   incidents.
4. **Better client information**: V2 allows more details about the client
   sending the event.

The v2 enhancements provide much richer context, helping responders understand
and fix incidents faster.

## Leveraging PagerDuty API Webhooks for Real-Time Notifications

[Webhooks](/learning-center/mastering-webhook-and-event-testing) complete the
picture for truly two-way PagerDuty integrations. While the REST and Events APIs
let you send data to PagerDuty, webhooks push real-time updates back to your
systems.

### Webhooks Overview

PagerDuty webhooks send notifications about incidents, alerts, and other events
to your applications as they happen. Key benefits include:

- Instant notification when incidents change
- Less API usage compared to polling
- Real-time data for dashboards
- Easy automation of downstream processes

### Setting Up Webhooks

Setting up webhooks in PagerDuty takes just a few steps:

1. Create a secure HTTPS endpoint in your application that can receive POST
   requests.
2. In your PagerDuty account, go to **Integration → Generic Webhooks** and click
   **Add Webhook**.
3. Enter your endpoint URL and pick the events you want to receive.
4. Add verification in your endpoint to confirm incoming webhook requests are
   authentic using the shared secret.

Your webhook endpoint should quickly return a 2xx status code to acknowledge
receipt. Any processing should happen asynchronously to avoid timeouts.

### Use Cases for Webhooks

Organizations use PagerDuty webhooks in clever ways to improve their incident
management:

1. **Service desk integration**: Automatically create tickets in Jira,
   ServiceNow, or Zendesk when PagerDuty incidents happen.
2. **Team communication**: Send targeted messages to Slack channels or Microsoft
   Teams when incidents affect specific services.
3. **Custom dashboards**: Power live incident dashboards showing current
   operational status. Utilizing
   [API monitoring tools](/learning-center/8-api-monitoring-tools-every-developer-should-know)
   can enhance the visibility and performance of these dashboards.
4. **Runbook automation**: Trigger automated fix scripts when specific types of
   incidents occur.
5. **Incident analytics**: Collect incident data in real-time for analysis and
   reporting. By leveraging
   [API usage analytics](/blog/analytics-for-developers-using-your-api), you can
   gain valuable insights from real-time incident data.

When implementing webhooks, security must be a priority. Verify all incoming
webhooks using the `X-PagerDuty-Signature` header, which contains an HMAC-SHA256
signature of the request body using your webhook's secret key.

## Advanced Integration Techniques

Building solid PagerDuty API integrations means tackling practical challenges
like [rate limits](/learning-center/api-rate-limiting), error handling, and
security. These techniques help create reliable, secure, and efficient
integrations.

### Implementing Caching to Improve Performance & Minimize Calls

Here's a quick tutorial on how to implement caching with Zuplo to minimize API
calls and improve your performance:

<YouTubeVideo videoId="9WZp-LLcLPM" />

### Handling Rate Limits and Error Responses

PagerDuty uses rate limits to keep the platform stable. A smart approach to
these limits is key for reliable integrations:

1. **Use Exponential Backoff**: When you hit rate limits (429 responses), use
   exponential backoff with jitter to retry safely.
2. **Be Proactive**: Watch the `X-RateLimit-Remaining` header and slow down
   requests as you approach limits.
3. **Batch Requests**: Use bulk endpoints where available to minimize API calls.
4. **Use Caching**: Cache data that doesn't change often, like users and
   services, to reduce API usage.

Implementing these strategies can prevent disruptions caused by rate limiting.
If you encounter "API Rate Limit Exceeded" errors, here's
[how to fix them](/learning-center/api-rate-limit-exceeded).

### Custom Solutions and Best Practices

The most effective PagerDuty implementations go beyond basic integrations to
create tailored solutions addressing specific operational challenges. Building
custom integrations can address specific operational challenges and extend your
platform's capabilities.

1. **Smart Alert Correlation**: Build middleware that analyzes incoming alerts
   before they reach PagerDuty. This can group related issues, enrich with
   context data, and apply custom routing logic. For example,
   [translating SQL queries into API requests](/learning-center/sql-query-to-api-request)
   can provide real-time data to enhance alert context.
2. **Automated Runbook Integration**: Attach relevant runbooks to incidents
   based on alert types. When critical incidents trigger, the system can
   automatically:
   - Load runbook steps directly into the incident timeline
   - Initiate preliminary diagnostic commands
   - Pre-populate troubleshooting data
   - Include links to related knowledge base articles
3. **Context-Aware Escalation**: Develop dynamic escalation policies that adapt
   based on incident context. This might escalate database issues differently
   than network outages, or adjust escalation timing based on customer impact
   severity.
4. **Self-Healing Systems**: Design systems where PagerDuty webhooks trigger
   automated remediation workflows before human intervention. For example, a
   cloud infrastructure team built a system that automatically:
   - Attempts restart of failed services
   - Scales up resources during load spikes
   - [Fails over](/learning-center/implementing-seamless-api-failover-systems)
     to backup systems
   - Creates incidents only when automation fails
5. **Incident Aggregation Dashboards**: Build executive-level dashboards that
   aggregate data from multiple monitoring systems and PagerDuty via APIs to
   show real-time operational health across the organization.

Leading organizations implement rigorous testing cycles for their PagerDuty
integrations, including regular "game days" where they simulate failures to
ensure their alerting and automation systems work as expected. This approach
helps identify gaps in coverage and refine alert thresholds to reduce both false
positives and missed issues.

### Security Best Practices

Security can't be an afterthought with PagerDuty integrations:

1. **Secure API Key Management**:
   - Never hardcode API keys in your code
   - Use a secrets manager for secure storage
   - Rotate keys regularly (at least quarterly)
   - Create service-specific API keys with minimal permissions
2. **Zero-Trust Implementation**:
   - Use TLS 1.2+ for all API traffic
   - Validate all webhook signatures with HMAC verification
   - Set up IP allowlists for webhook endpoints using
     [PagerDuty's published IP ranges](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-webhook-behavior#webhook-sources)
3. **Defense in Depth**:
   - Set request timeouts to prevent hanging connections
   - Add alerts for unusual API usage patterns
   - Log all API transactions for audits
   - Use OAuth 2.0 with short-lived tokens when possible

Implementing these
[API security best practices](/learning-center/api-security-best-practices)
ensures your integrations remain secure and compliant.

## Exploring PagerDuty API Alternatives

While PagerDuty offers a robust incident management platform, several
alternatives provide different approaches to API-driven incident management.

### Zuplo

While [Zuplo](https://portal.zuplo.com/signup?utm_source=blog) is not a direct
incident management platform, it serves as a programmable API gateway that can
augment incident workflows by enabling intelligent routing, authentication, and
transformation of alert and webhook data. For teams building custom incident
response pipelines, Zuplo offers:

- Serverless middleware for preprocessing webhook data before forwarding to
  tools like PagerDuty, OpsGenie, or Slack
- Built-in authentication, rate-limiting, and observability for alert-generating
  endpoints
- Easy integration with logging and monitoring tools to enforce policy at the
  edge
- JavaScript-based customization for custom response logic or throttling noisy
  alerts

Teams seeking to build more flexible and secure alert ingestion endpoints can
use Zuplo alongside traditional incident management APIs.

### OpsGenie

[OpsGenie](https://www.atlassian.com/software/opsgenie) offers a comparable API
structure with strong routing capabilities. Key differences include:

- More flexible team-based routing options
- Different approach to on-call scheduling APIs
- Enhanced mobile notification controls
- Simpler Jira integration for development teams

Many organizations find OpsGenie's API documentation more accessible for new
developers, though PagerDuty's API tends to offer more granular control for
complex scenarios.

### VictorOps (now Splunk On-Call)

[Splunk On-Call](https://www.splunk.com/en_us/products/on-call.html) provides a
unified observability approach with:

- Deep integration with Splunk's analytics platform
- Strong focus on post-incident learning APIs
- Built-in collaboration tools with API access
- Different webhook structure optimized for Splunk integration

Teams already using Splunk for monitoring may find this integration particularly
valuable.

### xMatters

[xMatters](https://www.xmatters.com/) focuses heavily on communication
workflows:

- Sophisticated escalation and notification APIs
- Advanced communication templates
- Strong integration with ITSM platforms
- Rich contextual data delivery to responders

xMatters often appeals to enterprise organizations with complex communication
requirements across departments.

### Open Source Alternatives

For teams seeking open-source alternatives:

- [**Prometheus Alertmanager**](https://prometheus.io/docs/alerting/latest/alertmanager/):
  Provides a simpler API focused primarily on alert routing and grouping
- [**OpenDistro for Elasticsearch**](https://opendistro.github.io/for-elasticsearch/):
  Offers alerting APIs deeply integrated with Elasticsearch
- [**Grafana OnCall**](https://grafana.com/products/cloud/oncall/): Newer option
  with growing API capabilities tightly integrated with Grafana

These options typically require more configuration but offer greater
customization potential and zero licensing costs.

### Integration Considerations

When evaluating alternatives to PagerDuty's API ecosystem, consider:

1. Your existing monitoring stack and required integrations
2. Specific webhook formats supported by your applications
3. Authentication methods and security requirements
4. Development resources available for implementation
5. Required customization level for your alerting workflows

Many organizations implement abstraction layers in their incident management
workflows, allowing them to switch between providers or use multiple providers
simultaneously without significant codebase changes.

## PagerDuty Pricing

PagerDuty offers several pricing tiers with different API access levels and
capabilities. Understanding these distinctions helps organizations choose the
right plan for their integration needs.

### Free Tier

The free tier includes basic API access with:

- Limited REST API access
- Core Events API functionality
- Basic webhook capabilities
- Restricted API call volume

While suitable for small teams or testing, the free tier has notable
restrictions on API usage and integration options.

### Professional Tier

The professional tier expands API capabilities with:

- Full REST API access
- Complete Events API functionality
- Advanced webhook configuration
- Higher API rate limits
- Service-level API keys
- Modern incidents API access

This tier meets most organizations' needs, especially those implementing custom
integrations or automations.

### Business Tier

For organizations requiring more sophisticated API usage:

- Extended API rate limits
- Advanced event intelligence features
- Custom fields in API responses
- Enhanced reporting API access
- Advanced analytics API integration
- API access to business service configuration

Enterprise organizations with complex operational needs often require this tier.

### Enterprise Tier

The enterprise tier provides the most comprehensive API access:

- Maximum API rate limits
- Full analytics API access
- Priority API support
- Custom API solutions
- Data retention API controls
- Advanced security features for API access

Organizations with mission-critical systems or regulatory requirements typically
need enterprise-level capabilities.

### API Access Considerations

When selecting a PagerDuty pricing tier, consider:

- Your expected API call volume
- Required data retention periods for API-accessible data
- Authentication and security requirements
- Custom field needs in your integration
- Number of services you'll connect via API
- Technical support requirements for your API implementation

PagerDuty offers custom pricing for organizations with specific API requirements
or unusually high API usage patterns.
[Visit their pricing page](https://www.pagerduty.com/pricing/incident-management/)
for detailed information on all these plans as well as custom pricing options.

## Optimize Incident Management with Pagerduty API

The PagerDuty API transforms incident management from a reactive process into a
streamlined, automated system. By integrating it into your operational
workflows, you detect issues faster, route them to the right teams
automatically, and resolve them more efficiently.

The most successful implementations combine the REST API, Events API, and
webhooks to create end-to-end automation that cuts manual work and speeds up
incident resolution. Whether you're building custom dashboards, connecting with
your monitoring stack, or creating ChatOps solutions, the PagerDuty API provides
the foundation for stronger operations.

Ready to take your API management to the next level? Zuplo can secure, manage,
and optimize your PagerDuty API integrations with powerful developer-friendly
tools.
[Sign up for a free Zuplo account](https://portal.zuplo.com/signup?utm_source=blog)
and see how we can help your team build more resilient, responsive incident
management workflows with just a few clicks.