Integrating with Atlassian Opsgenie

FireHydrant's Opsgenie integration enables various capabilities within the platform:

  • Automatically create FireHydrant incidents from Opsgenie alerts
  • Notify different channels based on incoming alert content
  • Page out to teams and services in Opsgenie from FireHydrant
  • Automatically pull in on-call responders from Opsgenie escalation policies to incident channels

Installation

Prerequisites

Make sure that the Opsgenie account authorizing the integration has API access. FireHydrant links and imports Opsgenie services through the link and import flow.

Connecting Opsgenie to FireHydrant

First, you need an Opsgenie API key.

  1. Go to the Opsgenie API Key Management page and click Add new API key.
  2. On the API Access page, click Create New API Key , enter a name for the key, and check the "Access rights" boxes for Read, Create and Update, and Configuration access.
Creating an API key in Opsgenie
Creating an API key in Opsgenie
  1. Click Add API key and then copy the API Key that is generated for you.

Now, we'll take that API key and connect Opsgenie to FireHydrant.

  1. Go to Settings > Integrations (new UI) or just Integrations on the left nav (old UI) and click on the Opsgenie integration.
  2. In the Opsgenie page, click Setup Opsgenie and enter the API key you copied.

Setup Outgoing Webhook

After configuring the connection, you will lastly need to configure an outgoing webhook from Opsgenie so FireHydrant can correctly sync incident states with it.

Get the webhook URL after setting up Opsgenie
Get the webhook URL after setting up Opsgenie
  1. In the Opsgenie integration settings page on FireHydrant, copy the webhook address provided by FireHydrant.
  2. In Opsgenie app, go to Settings > Integrations and click "+ Add Integration."
  3. Search for the Webhook integration and click on it.
  4. Check the Add alert description to payload and Add alert details to payload boxes on the configuration page. You may choose to edit what events you want to trigger an alert to FireHydrant by modifying the triggers, but we recommend leaving this as the default.
  5. Paste the copied webhook into the Webhook URL field and hit Save.
Setting up the outgoing webhook on Opsgenie
Setting up the outgoing webhook on Opsgenie

After Opsgenie is installed, you also have the ability to link and/or import Opsgenie services with/into FireHydrant's services. This enables multiple capabilities, including:

How to link/import services

  1. Head over to Service Catalog > Services and click the Add services dropdown and Import from third party.
  2. Click the Import button next to Opsgenie.
  3. From here, you can import all of your services, or you can load all of the available services in Opsgenie and selectively pick which ones you'd like to import or link.
Importing/linking services from Opsgenie to FireHydrant
Importing/linking services from Opsgenie to FireHydrant
  1. Tick the checkbox next to services you want to import/link, and then in the dropdown box, you can specify two choices:
    1. Create New - Will create a new entry in the FireHydrant service catalog with the same name as the Opsgenie service. This will also automatically link the new FireHydrant service and the Opsgenie Service.
    2. Link to Existing - If you already have services in FireHydrant, you can choose which one you'd like to link this Opsgenie service to.

Next Steps

Now that you've configured the Opsgenie integration, you can take the next steps to get the full power of FireHydrant + Opsgenie:


Opsgenie Alert Routing

Once your Opsgenie instance is configured, you can setup Alert Routes to take action on your alerts based on the data included in the alert. You can automatically open new incidents, send alerts to any Slack channel, log an alert in FireHydrant, or simply ignore it. To learn more, read about Alert Routes.

Opsgenie Caveat and Noise

For Opsgenie in particular, if you create an Incident in Opsgenie with Responders, you'll get multiple Alerts: one "associated alert" that notifies nobody, and then another alert that actually pages Responders. This seems to have been a deliberate decision by the Atlassian team, but this can cause a lot of noise on FireHydrant.

We don't currently have a way we can tell apart between the two alerts, so if you are using FireHydrant Alert Routing in conjunction with Opsgenie, we recommend only creating Alerts and not Incidents on Opsgenie when possible to avoid duplicate notifications/actions on FireHydrant.

Parameter Mappings

Here is the table of routable parameters on FireHydrant and the corresponding key/value from the inbound Opsgenie webhook(s). The $ refers to the webhook body content as a JSON object.

An explanation of Opsgenie's Webhook content can be found in their docs here.

Parameter Name Opsgenie Webhook Body Notes
Opsgenie: Action $.action The action taken that triggered this Webhook
Opsgenie: Impacted Services $.alert.details.impacted-services The services marked impacted on the alert from Opsgenie side
Opsgenie: Created At $.alert.createdAt When the alert was created
Opsgenie: Description $.alert.description Description of the alert or incident
Opsgenie: Priority $.alert.priority The Opsgenie alert's priority
Opsgenie: Alert ID $.alert.alertId ID of the alert in Opsgenie
Opsgenie: Message $.alert.message Alert message, or the Incident Summary if it's an incident
Opsgenie: Web URL $.alert.links.web Not all alerts have this parameter. If this parameter doesn't exist, FireHydrant reconstructs the URL for you and makes it available via Liquid templating

The following table is a mapping of our overall Alert Routing mapping object - these parameters are common across all Alert Routing/Monitoring integrations.

Parameter Name Opsgenie Webhook Body Notes
Alert Summary $.alert.message The same as Opsgenie: Message above
Alert Description $.alert.description The same as Opsgenie: Description above
Alert Priority $.alert.priority The same as Opsgenie: Priority above
Alert Status $.alert.action The same as Opsgenie: Action above
Alert Associated Infrastructure N/A The associated Service/Functionality in FireHydrant. In order for us to detect this, you must have linked a Service or Functionality to a service in Opsgenie.

Last updated on 9/15/2023