.png)
PagerDuty Integration Guide
Connect PagerDuty incident operations with enterprise systems through REST APIs, Events API v2, webhooks, and scheduled workflows.
PagerDuty integration options at a glance
PagerDuty provides REST APIs for incidents, services, users, teams, escalation policies, schedules, maintenance windows, and related operational resources. Its Events API v2 accepts monitoring and automation events that can trigger, acknowledge, or resolve incidents, while webhooks provide selected outbound incident and operational notifications. PagerDuty also supports change-event ingestion and analytics-oriented API access. Martini can consume these APIs, send event payloads, receive and verify webhook notifications, schedule reconciliation workflows, and map PagerDuty JSON into downstream systems. API keys and OAuth 2.0 support REST access, while Events API requests use service or routing keys.
| Integration point | Supported by PagerDuty? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Manage Incidents, Services, Users, Teams, Escalation Policies, Schedules, Maintenance Windows, and related PagerDuty resources. | Martini can consume PagerDuty REST endpoints, map JSON responses, apply business rules, and expose normalized APIs to downstream applications. |
| Events API v2 | Yes | Send monitoring or automation events that trigger, acknowledge, or resolve PagerDuty incidents. | Martini workflows can transform source alerts into Events API v2 payloads and submit them using a service or routing key. |
| Webhooks / outbound callbacks | Limited | Receive selected incident and operational notifications, including lifecycle changes such as triggering, acknowledgment, resolution, escalation, and reassignment where configured. | Martini can receive webhook requests, validate PagerDuty signatures, deduplicate events, enrich them through REST calls, and route them downstream. |
| Change events | Yes | Ingest deployment or infrastructure changes associated with PagerDuty services and incidents. | Martini can map deployment or infrastructure event data and send it to the documented PagerDuty change-event endpoint. |
| Analytics API | Limited | Retrieve analytics-oriented PagerDuty data for reporting, operational analysis, or warehouse feeds. | Martini can call the analytics API, paginate results, transform responses, and load selected data into reporting or storage systems. |
| Authentication | Yes | Authenticate REST requests with API keys or OAuth 2.0; authenticate Events API submissions with service or routing keys; verify webhook signatures. | Martini can keep API keys, OAuth secrets, routing keys, and webhook verification secrets in secure configuration and apply them at runtime. |
| Database access | No | PagerDuty does not provide direct database access for general integration synchronization. | Martini should use PagerDuty APIs and webhooks rather than attempting direct database connectivity. |
| GraphQL APIs | Not confirmed | No official general-purpose PagerDuty GraphQL API was confirmed. | Martini integrations should use the confirmed REST API, Events API, and webhook mechanisms instead. |
How PagerDuty exposes data and business events
PagerDuty REST APIs
PagerDuty REST APIs are the principal mechanism for managing incidents, services, users, teams, escalation policies, schedules, maintenance windows, and related resources. Collection responses may be paginated, and incremental retrieval behavior varies by resource.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to the REST API, retrieves one or more pages, maps PagerDuty JSON into a canonical model, applies validation and business rules, writes to target systems, and stores a checkpoint for the next run.
Implementation sequence
PagerDuty Events API v2
The Events API v2 receives monitoring or automation events and can trigger, acknowledge, or resolve incidents. It uses a service or routing key in the event payload rather than the conventional REST API authentication model.
Martini implementation pattern
Martini implementation pattern: a workflow receives an alert from a monitoring source, validates and enriches it, applies deterministic deduplication and state rules, constructs the Events API v2 payload, and submits it to PagerDuty with bounded retry handling.
Implementation sequence
PagerDuty Webhooks
PagerDuty webhooks provide selected outbound incident and operational notifications. Coverage is event-specific and does not guarantee notification for every PagerDuty object or field change.
Martini implementation pattern
Martini implementation pattern: a Martini API or webhook-triggered workflow validates the PagerDuty signature, stores or queues the notification, retrieves current PagerDuty context when necessary, and routes a normalized event to downstream applications.
Implementation sequence
PagerDuty Change Events
PagerDuty change-event ingestion records deployment or infrastructure changes associated with services and incidents. It is an inbound mechanism to PagerDuty and is distinct from outbound webhooks.
Martini implementation pattern
Martini implementation pattern: a workflow accepts deployment or infrastructure data, validates service correlation and required fields, maps the payload to PagerDuty's change-event contract, and submits it with observable error handling.
Implementation sequence
PagerDuty Analytics API
PagerDuty provides analytics-oriented API access for operational reporting and analysis. This is API access rather than direct database connectivity and should be synchronized according to the specific resource contract.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow retrieves analytics data with configured filters, handles pagination, transforms the response into a reporting model, and loads it into an approved data store or analytics application.
Implementation sequence
Common PagerDuty integration patterns
Pattern 1: Synchronize incidents with ServiceNow
When to use this pattern
Use this pattern when operational incidents must remain aligned with enterprise ITSM records and resolution status. Webhooks provide timely notifications, while REST enrichment ensures the target receives the current PagerDuty incident and service context.
Integration direction
Example Mapping
| PagerDuty Field | Canonical Field | Target Field |
|---|---|---|
| incident.id | sourceIncidentId | correlation_id |
| incident.title | incidentSummary | short_description |
| incident.status | lifecycleState | state |
| service.summary | serviceName | business_service |
Martini implementation pattern
Martini receives and verifies a PagerDuty webhook, stores the event identifier, retrieves the current incident and service, maps lifecycle states to ServiceNow values, and creates or updates the target record. Correlation keys and retry-safe writes prevent duplicate incidents when notifications are repeated or enrichment is temporarily unavailable.
Martini capabilities used
- workflows
- API consumption
- webhook reception
- data mapping
- business rules
- error handling
Pattern 2: Route monitoring events into PagerDuty
When to use this pattern
Use this pattern when Datadog, AWS CloudWatch, or another monitoring source requires centralized PagerDuty routing with organization-specific enrichment, filtering, and deduplication.
Integration direction
Example Mapping
| PagerDuty Field | Canonical Field | Target Field |
|---|---|---|
| alert.id | sourceAlertId | dedup_key |
| alert.title | eventSummary | payload.summary |
| alert.status | eventAction | event_action |
| service.name | serviceReference | routing_key |
Martini implementation pattern
Martini receives the monitoring alert, validates its source, enriches it with service ownership, determines whether it is a trigger, acknowledgment, or resolution, and submits an Events API v2 payload. A deterministic deduplication key and bounded retries reduce duplicate incidents and handle transient API failures.
Martini capabilities used
- workflows
- API consumption
- data transformation
- business rules
- API calls
- error handling
Pattern 3: Fan out PagerDuty notifications to collaboration tools
When to use this pattern
Use this pattern when teams need consistent, filtered incident notifications in Slack or Microsoft Teams without exposing raw PagerDuty payloads or duplicating routing logic in each collaboration integration.
Integration direction
Example Mapping
| PagerDuty Field | Canonical Field | Target Field |
|---|---|---|
| incident.priority.name | severity | messageSeverity |
| incident.status | lifecycleState | messageState |
| incident.html_url | incidentLink | messageLink |
| service.summary | serviceName | channelRouting |
Martini implementation pattern
Martini verifies selected PagerDuty webhook events, retrieves additional incident context when required, applies channel and severity rules, redacts fields, and publishes a normalized message. Delivery status is recorded so transient collaboration-platform failures can be retried without replaying unrelated events.
Martini capabilities used
- webhook reception
- workflows
- API consumption
- data mapping
- conditional routing
- error handling
Pattern 4: Reconcile on-call and service data
When to use this pattern
Use this pattern when an internal directory, CMDB, operations portal, or warehouse needs a reliable view of PagerDuty users, teams, services, escalation policies, or schedules. Scheduled reconciliation complements partial webhook coverage.
Integration direction
Example Mapping
| PagerDuty Field | Canonical Field | Target Field |
|---|---|---|
| service.id | serviceId | external_service_id |
| team.summary | owningTeam | owner_team |
| schedule.time_zone | scheduleTimeZone | time_zone |
| escalation_policy.summary | escalationPolicyName | escalation_policy |
Martini implementation pattern
A scheduled Martini workflow retrieves paginated resources, applies resource-specific checkpoints, maps relationships into the target model, and writes changes using stable PagerDuty identifiers. The workflow respects rate limits, preserves schedule time-zone context, and retries recoverable failures without reconstructing PagerDuty escalation logic locally.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination handling
- data mapping
- persistence
- error handling
Applications commonly integrated with PagerDuty
PagerDuty is commonly connected to IT service management, engineering, collaboration, monitoring, and customer-operation applications. Martini can orchestrate these flows while keeping PagerDuty-specific authentication, event handling, mappings, retries, and reconciliation logic separate from downstream systems.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| ServiceNow | Create and update ITSM incidents, associate operational incidents with change and configuration records, and coordinate resolution status. | PagerDuty → Martini → ServiceNow | Receive selected PagerDuty webhook notifications, verify signatures, retrieve current incident and service details through the REST API, map lifecycle states to ServiceNow fields, and send authorized updates back when required. |
| Jira | Create engineering follow-up, problem-management, or post-incident issues from PagerDuty incidents. | PagerDuty → Martini → Jira | Normalize PagerDuty incident events, apply routing rules for priority or service ownership, create or update Jira issues, and retain PagerDuty and Jira identifiers for idempotent updates. |
| Slack | Publish incident notifications, escalation messages, and responder updates to collaboration channels. | PagerDuty → Martini → Slack | Receive selected PagerDuty notifications, enrich them through the REST API, redact sensitive fields, format a channel-specific message, and publish it to the appropriate Slack destination. |
| Microsoft Teams | Distribute incident notifications and operational updates to Teams channels. | PagerDuty → Martini → Microsoft Teams | Route verified PagerDuty webhook events by service, priority, or escalation state, transform the payload into the target message format, and retry transient delivery failures. |
| Datadog | Send monitoring alerts into PagerDuty and preserve monitoring context for on-call response. | Datadog → Martini → PagerDuty | Receive Datadog alert payloads, apply deduplication and ownership rules, transform them into PagerDuty Events API v2 requests, and submit them with the appropriate routing key. |
| AWS CloudWatch | Route AWS alarms and operational events to PagerDuty for on-call response. | AWS CloudWatch → Martini → PagerDuty | Accept CloudWatch notifications, validate and enrich alarm data, map alarm state to trigger, acknowledge, or resolve semantics, and post the resulting event to PagerDuty. |
| Splunk | Forward notable events or search alerts to PagerDuty for incident creation and escalation. | Splunk → Martini → PagerDuty | Consume Splunk alert payloads, apply threshold and deduplication rules, construct an Events API v2 payload, and record the PagerDuty response for correlation. |
| Salesforce | Associate customer-impacting operational incidents with customer or case workflows. | PagerDuty → Martini → Salesforce | Match PagerDuty services or incidents to Salesforce customer context, map incident lifecycle changes to case updates, and use stored correlation identifiers to prevent duplicate case creation. |
How to build a PagerDuty integration in Martini
Objective
Establish controlled access to PagerDuty REST APIs, Events API v2, and webhook endpoints using the credential type appropriate to each flow.
Instructions in Martini
- Store REST API keys, OAuth secrets, routing keys, and webhook verification secrets in secure environment configuration.
- Configure PagerDuty API authentication and required headers for REST requests.
- Treat Events API routing keys separately from REST API credentials.
- Expose a protected Martini API or webhook-triggered workflow for PagerDuty notifications.
Objective
Select an event-driven, API-led, or scheduled entry point based on the completeness and latency requirements of the integration.
Instructions in Martini
- Use PagerDuty webhooks for selected near-real-time incident notifications.
- Use an external monitoring event as the trigger for Events API v2 submissions.
- Use a scheduler for reconciliation of incidents, services, users, teams, or schedules.
- Combine webhooks with scheduled REST reads when complete synchronization is required.
Objective
Obtain the current PagerDuty resource and related context rather than relying only on a partial notification payload.
Instructions in Martini
- Validate webhook signatures before processing the notification.
- Retrieve the current incident, service, or related resource when enrichment is required.
- Process every page of collection responses.
- Persist a page, timestamp, or object checkpoint for scheduled synchronization.
Objective
Coordinate validation, enrichment, routing, target calls, and response handling in a maintainable Martini workflow.
Instructions in Martini
- Store or enqueue inbound events before lengthy enrichment or fan-out operations.
- Apply explicit handling for triggered, acknowledged, and resolved incident states.
- Route events by service, team, priority, or ownership rules.
- Separate PagerDuty-specific processing from downstream application mappings.
Objective
Convert PagerDuty JSON and event payloads into canonical and target-specific representations.
Instructions in Martini
- Map Incidents, Services, Users, Teams, Escalation Policies, and Schedules using stable identifiers.
- Transform monitoring alerts into Events API v2 trigger, acknowledgment, or resolution payloads.
- Normalize timestamps, status values, ownership, and service references.
- Validate required fields before writing to target systems.
Objective
Enforce enterprise routing, deduplication, security, and data-quality policies before side effects occur.
Instructions in Martini
- Use deterministic correlation keys for incidents, alerts, and webhook events.
- Apply severity, service ownership, and escalation routing rules.
- Redact fields that should not be sent to collaboration or downstream systems.
- Reject unauthorized, malformed, or unsupported event types.
Common PagerDuty data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Incidents | Represent operational issues that are triggered, acknowledged, resolved, escalated, reassigned, or otherwise updated. | ServiceNow, Jira, Slack, Microsoft Teams, internal incident stores | Martini receives selected notifications, retrieves the current incident when needed, maps lifecycle states, applies idempotency, and synchronizes downstream records. |
| Services | Identify technical or business services responsible for handling incidents and associated escalation behavior. | ServiceNow CMDB, internal service catalogs, data warehouses, operations portals | Martini retrieves service metadata through the REST API, maps ownership and identifiers, and synchronizes changes on a schedule or during incident enrichment. |
| Users | Identify responders who can be assigned incidents, participate in teams, or receive notifications. | Internal directories, operations portals, reporting stores | Martini paginates user collections, applies permission-aware mappings, and stores PagerDuty identifiers for reconciliation. |
| Teams | Group users for access management, ownership, and operational responsibility. | ServiceNow, internal directories, service catalogs | Martini retrieves team data, maps ownership relationships, and synchronizes only the fields required by the target system. |
| Escalation policies | Define which users or schedules are notified when an incident is not acknowledged. | Service catalogs, operations portals, reporting systems | Martini retrieves policy relationships, preserves PagerDuty identifiers, and avoids reconstructing escalation behavior locally. |
| Schedules | Represent on-call rotations, overrides, and responder availability over time. | Operations portals, internal directories, reporting stores | Martini retrieves schedule and on-call information through the API, preserves time-zone context, and synchronizes it through controlled scheduled workflows. |
Authentication and security considerations
PagerDuty authentication
PagerDuty REST APIs support API-token authentication and OAuth 2.0 delegated access. API keys operate within the permissions of their associated PagerDuty user, while OAuth applications use requested scopes. Events API v2 uses a service or routing key in the event payload.
Webhook verification
PagerDuty webhook signatures and secrets should be validated before a notification enters downstream processing. Martini can keep API keys, OAuth client secrets, routing keys, and webhook verification secrets in secure environment configuration.
Least privilege
- Use an integration identity with only the required access to incidents, services, teams, schedules, or other resources.
- Do not embed credentials in mappings, payloads, or source code.
- Avoid writing webhook secrets or authorization values to application logs.
Operational considerations for PagerDuty integrations
Rate limits and pagination
PagerDuty applies API rate limits, and collection endpoints may paginate results. Martini workflows should process all pages, respect applicable response headers, use bounded backoff for HTTP 429 responses, and spread large synchronizations over scheduled runs.
Webhooks and reconciliation
PagerDuty webhooks cover selected events and may contain only part of the required data. A resilient design verifies the notification, stores an event identifier, retrieves current resource data when needed, and combines near-real-time processing with scheduled REST reconciliation.
Idempotency and state
- Use stable incident, alert, webhook, and source-event identifiers for correlation.
- Map triggered, acknowledged, and resolved states explicitly.
- Persist checkpoints for pages, timestamps, or object identifiers where incremental retrieval is supported.
Schema and operational resilience
PagerDuty API versions, webhook versions, and payloads can evolve. Validate required fields, isolate PagerDuty mappings from canonical models, test representative lifecycle events, and monitor authentication, permission, rate-limit, enrichment, and downstream delivery failures.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration across systems
Martini coordinates PagerDuty APIs, webhook entry points, monitoring sources, ITSM platforms, collaboration tools, databases, and internal APIs in a single workflow model. This avoids duplicating routing and retry logic across point-to-point scripts.
Reusable integration assets
Teams can expose normalized APIs, reuse PagerDuty enrichment and validation logic, and apply consistent mappings and business rules across ServiceNow, Jira, Slack, Microsoft Teams, and operational data stores.
Reliability and maintainability
- Use checkpoints, pagination handling, signature verification, idempotency, and bounded retries.
- Keep credentials and environment-specific settings outside workflow logic.
- Monitor workflow outcomes and isolate vendor-specific schema changes from downstream models.
Frequently asked questions
PagerDuty can be integrated through its REST APIs, Events API v2, selected webhooks, change-event ingestion, and analytics-oriented APIs. REST APIs manage operational objects, Events API v2 receives monitoring events, and webhooks notify external systems about selected PagerDuty events. Enterprise workflows commonly combine webhooks with scheduled REST reconciliation.
Yes. Martini can consume PagerDuty REST APIs, send Events API v2 payloads, receive and verify PagerDuty webhook notifications, schedule synchronization workflows, and map PagerDuty data into applications such as ServiceNow, Jira, Slack, Microsoft Teams, or internal stores.
No. A dedicated PagerDuty connector is not required. Martini can integrate using PagerDuty's confirmed native mechanisms, including REST APIs, Events API v2, webhooks, change-event endpoints, API keys, OAuth 2.0, routing keys, and webhook signatures.
Lonti does not charge an additional per-connector or per-vendor fee to integrate PagerDuty. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from PagerDuty, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use the REST API for incidents, services, users, teams, escalation policies, schedules, and related resources. Use Events API v2 to send monitoring or automation events into PagerDuty. Use webhooks for selected outbound notifications and scheduled REST workflows for reconciliation. No general-purpose PagerDuty GraphQL or SOAP API was confirmed.
Yes. Martini can receive PagerDuty webhook notifications through an API or webhook-triggered workflow and validate their signatures before processing. PagerDuty webhooks cover selected event types rather than every object or field change, so they should normally be combined with REST API reconciliation. Martini can also send events to PagerDuty through Events API v2.
Martini can map PagerDuty JSON into canonical and target-specific models, explicitly translate incident states, and preserve PagerDuty identifiers for correlation. Webhook and monitoring-event flows should use stable event or incident identifiers and deterministic deduplication keys. Scheduled workflows should paginate through collections and store checkpoints.
A Martini workflow can distinguish authentication, permission, validation, rate-limit, missing-resource, network, and service failures. It can honor applicable rate-limit information, use bounded exponential backoff, retry recoverable failures, record processing status, and avoid duplicate downstream writes through idempotent correlation. API keys and OAuth permissions should be limited to the required PagerDuty access.
Related Martini documentation
Workflows
Connect PagerDuty with Martini
Use Martini to build reliable PagerDuty integrations that combine REST APIs, Events API v2, verified webhooks, scheduled reconciliation, and reusable enterprise workflows.