Pagerduty Provider

​

Description

The Pagerduty Provider enables integration with PagerDuty to create, manage, and synchronize incidents and alerts within Keep. It supports both direct API key authentication and OAuth2, allowing greater flexibility for secure integration.

​

Authentication

This provider requires authentication.

• routing_key: Routing Key (an integration or ruleset key) (required: False, sensitive: False)
• api_key: Api Key (a user or team API key) (required: False, sensitive: True)
• oauth_data: For oauth flow (required: False, sensitive: True)
• service_id: Service Id (if provided, keep will only operate on this service) (required: False, sensitive: False)

Certain scopes may be required to perform specific actions or queries via the provider. Below is a summary of relevant scopes and their use cases:

• incidents_read: Read incidents data. (mandatory)
• incidents_write: Write incidents.
• webhook_subscriptions_read: Read webhook data.
• webhook_subscriptions_write: Write webhooks.

​

In workflows

This provider can be used in workflows.

As “step” to query data, example:

steps:
    - name: Query pagerduty
      provider: pagerduty
      config: "{{ provider.my_provider_name }}"
      with:
        incident_id: {value}  

As “action” to make changes or update data, example:

actions:
    - name: Query pagerduty
      provider: pagerduty
      config: "{{ provider.my_provider_name }}"
      with:
        title: {value}  # Title of the alert or incident
        dedup: {value}  # String used to deduplicate alerts for events API, max 255 chars
        service_id: {value}  # ID of the service for incidents
        requester: {value}  # Email of the user requesting the incident creation
        incident_id: {value}  # Key to identify the incident. UUID generated if not provided
        event_type: {value}  # Event type for events API (trigger/acknowledge/resolve)
        severity: {value}  # Severity for events API (critical/error/warning/info)
        source: {value}  # Source field for events API
        priority: {value}  # Priority reference ID for incidents
        status: {value}  # Status for incident updates (resolved/acknowledged)
        resolution: {value}  # Resolution note for resolved incidents
        body: {value}  # Body of the incident as per https://developer.pagerduty.com/api-reference/a7d81b0e9200f-create-an-incident#request-body
        kwargs: {value}  # Additional event/incident fields

Check the following workflow example:

• ifelse.yml

​

Topology

This provider pulls topology to Keep. It could be used in correlations and mapping, and as a context for alerts and incidents.

​

Connecting with the Provider

To connect Keep to PagerDuty:

• Routing Key: Use for event posting via the PagerDuty Events API. In the PagerDuty UI, this is displayed as the integration key.
• API Key: Use for incident creation and management through the PagerDuty Incidents API.
• Service Id (Optional): If provided, keep operates within the service’s scope.
• OAuth2: Token management handled automatically by Keep.

​

Enabling OAuth in the open-source version

If you would like to use OAuth in the open-source, where you self-host Keep, you can do so by following these step:

1. Create a PagerDuty account
2. In the account page, go to Integrations > App Registration
3. Click on New App blue button on the top right
4. Fill in the required fields
5. Select “OAuth 2.0” in the Functionality section and click Next
6. In the Redirect URL, you need to add Keep’s PagerDuty OAuth2 redirect URL, which is based on your deployments URL. For example, if Keep is deployed at http://localhost:3000, the redirect URL is http://localhost:3000/providers/oauth2/pagerduty
7. In the Authorization section, select Scoped OAuth and select the following scopes:

• Abilities: Read Access
• Incidents: Read/Write Access
• Services: Read/Write Access
• Webhook Subscriptions: Read/Write Access

8. Click on Register App blue button on the bottom right
9. Copy the Client ID and Client Secret from the OAuth 2.0 Client Information modal and set the PAGERDUTY_CLIENT_ID and PAGERDUTY_CLIENT_SECRET environment variables in your Keep backend deployment.

​

PagerDuty Webhook Integration

By default, when Keep installs itself as a webhook integration, it subscribes to all incident events (“Account Scope”).

If you wish to limit Keep to some specific services, you can do so by selecting the Service scope and selecting the services you want to subscribe to.

Find this page under Integrations > Generic Webhooks (v3)

​

Notes

The provider uses either the events API or the incidents API to create an alert or an incident. The choice of API to use is determined by the presence of either a routing_key or an api_key.

An expired trial while using the free version of PagerDuty may result in the “pagerduty scopes are invalid” error at Keep.

​

Webhook Integration Modifications

The webhook integration adds Keep as a destination within the “Integrations” API within Pagerduty. This grants Keep access to the following scopes within Pagerduty:

• webhook_subscriptions_read
• webhook_subscriptions_write

​

Useful Links

• Pagerduty Events API documentation: https://v2.developer.pagerduty.com/docs/send-an-event-events-api-v2
• Pagerduty Incidents API documentation: https://v2.developer.pagerduty.com/docs/create-an-incident-incidents-api-v2