PagerDuty Notifier

Getting Started#

Setup PagerDuty#

The PagerDuty Alarm Handler requires an integration-key to communicate with the PagerDuty API. This guide assumes you have a PagerDuty application ready and will add a new Service Integration

Visit the Services -> Service Directory page and click the service that you want to add the alarm integration with.

On the Integrations tab click +Add another integration and search for and select the Curity Identity Server integration.

This adds a new integration to the list in your service. Click the down arrow to expand the service and see the integration keys.

When the integration is setup in PagerDuty, you have the integration-key and the integration-url. The URL looks as follows:

https://events.pagerduty.com/v2/enqueue

The URL should be used when configuring the Alarm Handler in the Curity Identity Server as below:

• hostname = events.pagerduty.com
• context = /v2/enqueue
• port = 443

Create Curity PagerDuty Notifier#

To create a new Email Notifier, navigate to System → Alarm Handlers and click the New Alarm Handler button. Give a name to the handler and, select the PagerDuty handler type.

Finally, provide the required configuration properties for the new handler and commit the configuration.

Configuration#

To configure the PagerDuty alarm handler, an HTTP client needs to be configured, along with the path, host and port to connect to. Any authentication mechanism is configured on the HTTP client, which supports Mutual TLS, Basic Authentication and OAuth Client Credentials.

The alarm handler is configured under configuration-reference/environments/environment/alarms/alarm-handlers/alarm-handler

# A configured PagerDuty handler shown in the CLI

% show environments environment alarms alarm-handlers alarm-handler pd1
pagerduty-notifier {
    web-service {
        hostname    events.pagerduty.com;
        port        443;
        context     /v2/enqueue;
        http-client defaultHttpClient;
    }
    integration-key  8f88*****4;
}

Message Format#

The PagerDuty format is built to provide a readily compatible message. By integrating with PagerDuty, the alarm handler will emit events that create alerts in the PagerDuty console. The message format does not require transformation in PagerDuty, instead it is pre-mapped to the Event API v2.

The following mapping is used:

{
    "routing_key": "<THE CONFIGURED INTEGRATION KEY>",
    "dedup_key": "<UNIQUE ALARM IDENTIFIER>",
    "event_action": "trigger",
    "payload": {
        "summary": "<BRIEF DESCRIPTION>",
        "severity": "<REMAPPED SEVERITY>",
        "source": "<RESOURCE_TYPE:RESOURCE_ID@NODE_ID>",
        "timestamp": "<LAST UPDATED>",
        "component": "<ALARMING RESOURCE ID>",
        "group": "<ALARMING RESOURCE TYPE>",
        "class": "<ALARM TYPE>",
        "custom_details": {
            "dashboard_link": "<URL>",
            "brief_description": "<STRING>",
            "detailed_description": ["<STRING>"],
            "suggested_actions": ["<STRING>"],
            "impact_descriptions": {
                "<TYPE>": {
                    "title": "<STRING>",
                    "impacted_dependencies": ["<STRING>"]
                }
            }
        }
    },
    "links": [
        {
            "href": "<DASHBOARD LINK TO ALARM>",
            "text": "View alarm in Curity dashboard"
        }
    ]
}

The alarm severity is remapped according to the following scheme: