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.

3. 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.

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.

Link Opsgenie Services to FireHydrant Services

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:

• From Slack, directly paging out to teams or finding who's on call for a particular service
• Automatically paging owners of a particular service when it's marked impacted in a FireHydrant incident

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.

4. 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:

• Configure teams to pull in users from on-call schedules.
• Configuring Alert Routing to automatically open incidents or post notifications from inbound alerts.
• Automatically create Splunk On-Call incidents via Runbook step

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.

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