PagerDuty

Important

PagerDuty is deprecating use of existing Webhook v1/v2 Extensions in favor of Webhook v3 Subscriptions. For more information, see PagerDuty Webhooks.

The 1.2 version of the PagerDuty integration introduces support for Webhook v3 Subscriptions:

  • New webhooks installed by the integration will be created as Webhook v3 Subscriptions.

  • Any existing Webhook v2 Extensions already installed an earlier version of the integration will be retained

  • A new check box “Migrate existing Extensions to Subscriptions” allows existing Webhook v2 Extensions to be migrated to Webhook v3 Subscriptions. It is unchecked by default.

Customers using PagerDuty are encouraged to install the latest Add-Ons version and use the migration option to move their existing existing Webhook v2 Extensions to be migrated to Webhook v3 Subscriptions before 31 March 2022.

You can install the PagerDuty integration to enable bidirectional communication between Moogsoft Enterprise and PagerDuty. The integration allows you to send events to PagerDuty from Moogsoft Enterprise alerts and Situations. Each event relates to a service which creates a PagerDuty incident.

Notes you add to a PagerDuty incident appear in Moogsoft Enterprise as collaboration posts in related Situations. Likewise, posts you add to a Situation appear in the PagerDuty incident notes.

See the PagerDuty documentation documentation for details on PageDuty components.

When you configure the PagerDuty integration, Moogsoft Enterprise automatically creates a 'Notify PagerDuty' Situation workflow which notifies PagerDuty of new Situations. See Workflow Engine for more information.Workflow Engine

You can also use the following workflow engine functions in alert and Situation workflows to interact with this integration:

  • createNotification: Triggers this integration to create a PagerDuty incident for the related alert or Situation.

  • ackNotification: Acknowledges any associated PagerDuty incidents for the related alert or Situation.

  • resolveNotification: Resolves any associated PagerDuty incidents for the related alert or Situation.

Before You Begin

The PagerDuty integration has been validated with the PagerDuty SaaS offering. Before you start to set up your integration, ensure you have met the following requirements:

  • You have the "user" ("manager") role and an API User Token for it. This role is required to query services for integrations, create integrations and extensions via the API. 

    If you do not want to assign the "user" role, you must set up PagerDuty integrations and extensions manually. See the "Configure PagerDuty" section below for more information.

  • You have the "responder" team role for all relevant teams and services. You require this role to create, acknowledge, and resolve incidents related to those teams and services.

  • You have ensured that Moogsoft Enterprise roles for users that access alert and Situation tools have the "moolet_informs" permission.

Configure the PagerDuty Integration

To configure the PagerDuty integration:

  1. Navigate to the Integrations tab.

  2. Click PagerDuty in the Notification and Collaboration section.

  3. Provide a unique integration name. You can use the default name or customize the name according to your needs.

  4. Provide connection details for your PagerDuty system and configure service mappings. See PagerDuty Integration Workflow more for information.

Configure PagerDuty

NOTE: The setting Automatically Create Integrations & Subscriptions was formerly called Automatically Create Integrations & Extensions.

Determine your Automatically Create Integrations & Subscriptions setting:

  • If Automatically Create Integrations & Subscriptions is enabled, you do not need to perform any integration-specific steps in PagerDuty. The integration creates subscriptions and integrations with the name "Moogsoft-Integration" and updates the URL of any existing subscriptions of the same name to this value.

    If you select this option when creating the integration but uncheck it afterward, these items are not automatically removed. You must remove them from PagerDuty. They are named Moogsoft-Integration to make them easy to locate.

    OR,

  • If Automatically Create Integrations & Subscriptions is disabled, you must manually create the integrations and subscriptions. For each service, you must name the integration and subscription "Moogsoft-Integration."

    1. Depending on your service incident behavior, to create an integration for each PagerDuty service you require either an "Events API v1" or "Events API v2" integration for Moogsoft Enterprise to create PagerDuty events.

    2. Create a "Generic Webhook (v3)" subscription for each service so that PagerDuty can post incident updates to Moogsoft Enterprise. Ensure the URL is in the following format:

      "https://<graze-username>:<graze-password>@example.com/graze/v1/integrations/pagerduty"

      and that the following event subscriptions are selected:

      • incident.triggered

      • incident.acknowledged

      • incident.resolved

      • incident.annotated

    To remove the PagerDuty integration, you must remove the integrations and subscriptions in both Moogsoft Enterprise and PagerDuty.

    If the integration fails to connect to one or more sources, Moogsoft Enterprise creates an alert and writes the details to the process log. Refer to the logging details for LAMs and integrations for more information.