Pagerduty Provider
Pagerduty Provider allows integration with PagerDuty to create, manage, and synchronize incidents and alerts within Keep.
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)
In workflows
This provider can be used in workflows.
As “step” to query data, example:
As “action” to make changes or update data, example:
Check the following workflow example:
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.
You can find your routing key in the PagerDuty (integration key in PagerDuty UI) web app under Services > Service Directory > Your service > Integrations > Expand Events API, and select the integration you want to use. You can find your API key in the PagerDuty web app under Configuration > API Access.
The routing_key is used to post events to PagerDuty using the events API. The api_key is used to create incidents using the incidents API.
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:
- Create a PagerDuty account
- In the account page, go to Integrations > App Registration
- Click on New App blue button on the top right
- Fill in the required fields
- Select “OAuth 2.0” in the Functionality section and click Next
- 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
- 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
- Click on Register App blue button on the bottom right
- Copy the Client ID and Client Secret from the OAuth 2.0 Client Information modal and set the
PAGERDUTY_CLIENT_ID
andPAGERDUTY_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)
Scopes
Certain scopes may be required to perform specific actions or queries via the Pagerduty Provider. Below is a summary of relevant scopes and their use cases:
- incidents_read (Incidents Read) Required: True Description: View incidents.
- incidents_write (Incidents Write) Required: False Description: Write incidents.
- webhook_subscriptions_read (Webhook Subscriptions Read) Required: False Description: View webhook subscriptions. (*Required for auto-webhook integration)
- webhook_subscriptions_write (Webhook Subscriptions Write) Required: False Description: Write webhook subscriptions. (*Required for auto-webhook integration)
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