OpsGenie Integration for Incident Alert and Acknowledgement

For Netreo to receive API-based incident acknowledgements from OpsGenie, users must send the OpsGenie payloads to Netreo's OpsGenie ITSM Integration API rather than the normal Acknowledgement API. This requires several setup steps beforehand.

• Configuring OpsGenie
• Configuring Netreo

Note: Netreo incidents cannot currently be unacknowledged from OpsGenie. De-acknowledging Netreo incidents will need to be done manually, on an as-needed basis.

For API documentation, see OpsGenie ITSM Integration API

OpsGenie Setup

For Netreo to be able to send incident alerts to -- and receive incident acknowledgements from -- OpsGenie, your OpsGenie account must have a team configured for this purpose. This can be an existing team or one specifically dedicated to Netreo.

The team will require two integrations be added to it to work with Netreo.

• Netreo to OpsGenie - To allow OpsGenie to receive incident alerts from Netreo
• OpsGenie to Netreo - To allow OpsGenie to send incident acknowledgements to Netreo

Follow the steps below to add these integrations to your OpsGenie team.

1. Log in to your OpsGenie account.
2. Select Teams at the top of the page to open the Teams page.
3. Select the team you wish to use for Netreo integration to configure that team. (If you have not already created a team to use with Netreo, you may do so now by selecting Add Team.)
4. In the team configuration, select Integrations from the menu on the left.
5. Add a "Netreo to OpsGenie" integration:
   1. On your team's Integrations page, select the Add Integration button.
   2. Select the API integration type to add it.
      1. Name the integration. (We suggest something easily identifiable like "Netreo to OpsGenie")
      2. Ensure the correct team is selected.
      3. Select Continue.
      4. Select Turn On Integration.
   3. On your team's Integrations page, select the newly added integration to edit it.
      1. In the Integration settings section, select the Edit button.
      2. Ensure the following options are checked:
         • Allow Read Access
         • Allow Create and Update Access
         • Allow Delete Access
         • Allow Configuration Access
      3. Copy the provided API key. (You will need this to configure Netreo later.)
      4. Save your integration.
         • You may leave all other settings at the default or configure as required for your organization.
6. Now, add an "OpsGenie to Netreo" integration:
   1. On your team's Integrations page, select the Add Integration button.
   2. Select the Webhook type to add it.
      1. Name the integration. (We suggest something easily identifiable like "OpsGenie to Netreo")
      2. Ensure the correct team is selected.
      3. Select Continue.
      4. Select Turn On Integration.
   3. On your team's Integrations page, select the newly added integration to edit it.
      1. Ensure the following alert options are checked:
         • Post to Webhook URL for OpsGenie alerts
         • Alert is acknowledged
      2. In the Integration settings section, select the Edit button.
      3. Ensure the following options are checked:
         • Authenticate with a Webhook account
           • Under webhook URL enter the public-facing URL of your Netreo instance pointing to the Netreo OpsGenie ITSM Integration API (e.g., instanceURL/api/webhook/opsgenie_itsm.php). (The URL to use for a Netreo SaaS deployment is https://netreo.cloud/api/webhook/opsgenie_itsm.php)
           • Under custom headers select Add extra property
             • In the first field, enter Authorization
             • In the second field, enter the base64 encoded hash of your Netreo API credentials (consisting of a username and your Netreo API key for the password) using the basic authorization type (e.g., Basic cGFzc3dvcmRoZXJl'). The username used in the hash is ignored by the API, so it can be anything. Only the Netreo API key is important. (This hash can be created using any API client, such as Postman. Remember to use the basic authorization type when creating the hash.)
             • Select the checkmark to add the header.
           • (If you are using a Netreo SaaS deployment) Under custom headers select Add extra property
             • In the first field, enter X-Netreo-pin
             • In the second field, enter your Netreo SaaS API PIN number.
             • Select the checkmark to add the header.
      4. Save your integration.
         • You may leave all other settings at the default or configure as required for your organization.

Your OpsGenie account is now set up for incident acknowledgement integration with Netreo using the default OpsGenie webhook payload mapping for incident history display. If you wish to use custom mapping for the OpsGenie payload, see the next section Custom Mapping.

Custom Mapping

This section includes instructions for customizing the incident acknowledgement API call that OpsGenie makes to Netreo's OpsGenie ITSM Integration API to acknowledge an incident.

There are three internal fields in Netreo that are used to display acknowledgement information:

• incident_id - The ID of the Netreo incident being acknowledged. (By default, Netreo maps the alert.alias value of the OpsGenie webhook payload to this field.)
• ack_user - The username used to show who acknowledged an incident. (By default, Netreo maps the alert.username value of the OpsGenie webhook payload to this field.)
• ack_comment - The text to display for an incident acknowledgement comment.  (By default, Netreo maps the alert.message value of the OpsGenie webhook payload to this field.)

If you would like Netreo to use other values from the OpsGenie webhook payload for these fields, the API call made by OpsGenie to Netreo when acknowledging an incident may include additional headers to customize the mapping of these fields. (Customizing these fields requires knowledge of the OpsGenie payload structure. For an example of the OpsGenie payload structure go to https://support.atlassian.com/opsgenie/docs/opsgenie-edge-connector-alert-action-data/)

To customize the mapping for any or all of these fields, follow the steps below.

1. Log in to your OpsGenie account.
2. Select Teams at the top of the page to open the Teams page.
3. Select the team used for Netreo incident acknowledgement to configure the team.
4. In the team configuration, select Integrations from the menu on the left.
5. On your team's Integrations page, select the OpsGenie to Netreo integration you created to edit it.
6. In the Integration settings section, select the Edit button.
7. For each field you wish to custom map (steps a-d below must be repeated for each field to be remapped):
   1. Under custom headers select Add extra property
   2. In the first field, enter "X-Netreo-FieldRemap"
   3. In the second field, enter the field name (in quotes) you would like to remap and the payload source you would like to map it to (also in quotes) in JSON format (e.g., {"ack_comment" : "$.alert.userId"})
   4. Select the checkmark to add the header.
8. Save your integration.

The fields you have included headers for will now use the payload source specified as their value in Netreo.

Netreo Setup

First, make sure API access is enabled in Netreo - How to Enable Netreo API Access

To set up Netreo for OpsGenie incident acknowledgement, follow these steps.

1. Log in to Netreo as a user with the SuperAdmin access level.
2. Install the OpsGenieAlert action group  from the Netreo cloud library:
   1. From the main menu select Administration >> Alerts >> Actions to navigate to the Actions Administration page.
   2. Select the Actions Cloud Library button to navigate to the Actions Cloud Library page.
   3. Using the search box, search for OpsGenieAlert.
   4. Once located, select the download icon in its ACTIONS column to download and install the OpsGenieAlert action group.
3. Edit the OpsGenieAlert action group to work with your OpsGenie account:
   1. On the Actions Cloud Library page select the Actions Administration button to navigate to the Actions Administration page.
   2. Locate the OpsGenieAlert action group.
   3. Within the action group, locate the OpsGenie Alert action.
   4. Within the action, locate the "api.opsgenie.com/v2/alerts" webhook method.
   5. Select the Edit Method icon in the method's ACTIONS column to edit the webhook.
      1. In the PAYLOAD field, after "Authorization" replace the text "INSERT CUSTOMER API KEY HERE" with your OpsGenie API key. (Retrieved when creating the Netreo to OpsGenie team integration in the OpsGenie Setup section above.) Do not delete the "GenieKey " part of the text. (The final result should similar to this: "Authorization" : "GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'")
      2. Select the Edit Method button to save the method.

Netreo is now set up to send alerts to your OpsGenie account.

After completing both the OpsGenie setup steps and the Netreo setup steps, Netreo will send incident alert notifications to your OpsGenie account and allow you to acknowledge those incidents from within OpsGenie.