|
| 1 | +--- |
| 2 | +title: "Opsgenie Compatible Alert Integration" |
| 3 | +description: "Push alerts to Flashduty On-call with the Opsgenie Alert API protocol. Tools that already send to Opsgenie only need a new API URL." |
| 4 | +keywords: ["alert integration", "Opsgenie", "Alert API", "Alertmanager", "Grafana", "migration"] |
| 5 | +--- |
| 6 | + |
| 7 | +Flashduty implements alert creation and closing from the Opsgenie Alert API, with the same request and response formats as Opsgenie. Tools that already send alerts to Opsgenie (such as Prometheus Alertmanager and Grafana Alerting) push alerts to Flashduty On-call once you replace the Opsgenie API URL with the Flashduty push URL. |
| 8 | + |
| 9 | +<div className="hide"> |
| 10 | + |
| 11 | +## In Flashduty On-call |
| 12 | +--- |
| 13 | + |
| 14 | +You can get the push URL in either of two ways. |
| 15 | + |
| 16 | +### Dedicated integration |
| 17 | + |
| 18 | +1. In the Flashduty console, select **Channels** and open a channel |
| 19 | +2. Select **Settings** → **Integrations** → **Dedicated Integrations**, then click **Add an Integration** |
| 20 | +3. Select **Opsgenie Compatible** and click **Save** |
| 21 | +4. Open the generated integration card and copy the **Push URL** |
| 22 | + |
| 23 | +### Shared integration |
| 24 | + |
| 25 | +1. In the Flashduty console, select **Integration Center → Alert Events** |
| 26 | +2. Select **Opsgenie Compatible** and enter an integration name |
| 27 | +3. Configure the default route and pick a channel; you can add more rules under **Routes** after creating it |
| 28 | +4. Click **Save** and copy the generated **Push URL** |
| 29 | + |
| 30 | +</div> |
| 31 | + |
| 32 | +## Push URL |
| 33 | +--- |
| 34 | + |
| 35 | +The push URL has this format, with `integration_key` as part of the path: |
| 36 | + |
| 37 | +``` |
| 38 | +{api_host}/event/push/alert/opsgenie/<integration_key>/ |
| 39 | +``` |
| 40 | + |
| 41 | +Opsgenie clients append paths such as `v2/alerts` and `v2/alerts/<alias>/close` to the API URL, which can drop an `integration_key` query parameter or put it in the wrong place, so Flashduty reads `integration_key` from the path. The `Authorization: GenieKey <key>` header is not used for authentication; if the client requires it, enter any non-empty value. |
| 42 | + |
| 43 | +Supported endpoints: |
| 44 | + |
| 45 | +| Opsgenie endpoint | Request | Flashduty handling | |
| 46 | +| :--- | :--- | :--- | |
| 47 | +| Create Alert | `POST v2/alerts` | Creates or updates an alert | |
| 48 | +| Close Alert | `POST v2/alerts/<alias>/close?identifierType=alias` | Recovers the alert | |
| 49 | +| Acknowledge, Add Note, Update Message, Update Description and others | `POST` or `PUT v2/alerts/<alias>/<action>` | Returns 202, no action taken | |
| 50 | + |
| 51 | +A successful request returns HTTP 202 and `{"result": "Request will be processed", "took": 0, "requestId": "..."}`, the same as Opsgenie. |
| 52 | + |
| 53 | +## Configure in Prometheus Alertmanager |
| 54 | +--- |
| 55 | + |
| 56 | +Add `opsgenie_configs` to a receiver in `alertmanager.yml` and set `api_url` to the push URL: |
| 57 | + |
| 58 | +```yaml |
| 59 | +receivers: |
| 60 | + - name: flashduty |
| 61 | + opsgenie_configs: |
| 62 | + - api_key: any-non-empty-value |
| 63 | + api_url: https://api.flashcat.cloud/event/push/alert/opsgenie/<integration_key>/ |
| 64 | + send_resolved: true |
| 65 | + priority: '{{ if eq .CommonLabels.severity "critical" }}P1{{ else }}P3{{ end }}' |
| 66 | +``` |
| 67 | +
|
| 68 | +<Warning> |
| 69 | +`api_url` must end with `/`. Alertmanager appends `v2/alerts` directly to the URL, so without the trailing `/` the path is wrong and the request returns 404. |
| 70 | +</Warning> |
| 71 | + |
| 72 | +- Only with `send_resolved: true` does Alertmanager send a Close request when the alert resolves |
| 73 | +- Alertmanager puts the common labels of the group in `details` by default, and Flashduty keeps them as alert labels |
| 74 | +- Without `priority`, Opsgenie's default `P3` applies, which is Warning |
| 75 | +- The Update Message and Update Description requests sent with `update_alerts: true` are accepted and ignored; the title and description update with the next Create request |
| 76 | + |
| 77 | +## Configure in Grafana |
| 78 | +--- |
| 79 | + |
| 80 | +<Steps> |
| 81 | +<Step title="Create an OpsGenie contact point"> |
| 82 | + |
| 83 | +1. Go to **Alerting → Contact points** and click **+ Add contact point** |
| 84 | +2. Set **Integration** to **OpsGenie** |
| 85 | +3. Enter any non-empty value in **API Key** |
| 86 | +4. Set **Alert API URL** to the push URL followed by `v2/alerts`: |
| 87 | + |
| 88 | + ``` |
| 89 | + https://api.flashcat.cloud/event/push/alert/opsgenie/<integration_key>/v2/alerts |
| 90 | + ``` |
| 91 | + |
| 92 | +5. Select **Auto close incidents**; otherwise Grafana sends no Close request when the alert resolves |
| 93 | +6. Keep **Send notification tags as** at the default **Tags**, or choose **Tags & Extra Properties** |
| 94 | + |
| 95 | +</Step> |
| 96 | + |
| 97 | +<Step title="Route alerts to it"> |
| 98 | + |
| 99 | +In **Notification policies**, route the alerts you want to push to this contact point. |
| 100 | + |
| 101 | +</Step> |
| 102 | + |
| 103 | +<Step title="Verify the lifecycle"> |
| 104 | + |
| 105 | +Let an alert rule go to Firing and confirm Flashduty receives the alert; then let the rule return to Normal and confirm the same alert recovers. |
| 106 | + |
| 107 | +</Step> |
| 108 | +</Steps> |
| 109 | + |
| 110 | +Grafana sends alert labels in `tags` as `key:value`, and Flashduty turns them back into labels of the same name. Grafana sends no `priority` by default, so `P3` (Warning) applies. To set the severity per rule, turn on **Override priority** in the contact point and add the label `og_priority` with a value from `P1` to `P5` to the alert rule. |
| 111 | + |
| 112 | +The contact point's **Test** button uses a new alias on every press, so each press opens a separate Warning alert in Flashduty that never recovers on its own. Close it by hand. |
| 113 | + |
| 114 | +## Other tools |
| 115 | +--- |
| 116 | + |
| 117 | +Any tool that lets you change the Opsgenie API URL and closes alerts by alias works with this integration: replace the API URL with the push URL (with or without `v2/alerts`, depending on how the tool appends paths), and send Close requests with `identifierType=alias`. |
| 118 | + |
| 119 | +Not supported: |
| 120 | + |
| 121 | +- **Closing by id or tiny id**: Flashduty does not issue Opsgenie alert IDs, so `identifierType` set to `id`, `tiny` or left empty returns 422 |
| 122 | +- **Read endpoints**: `GET` requests (such as `v2/alerts/requests/<requestId>`) are not supported. Zabbix's built-in Opsgenie media type polls that endpoint; use the [Zabbix integration](/en/on-call/integration/alert-integration/alert-sources/zabbix) instead |
| 123 | +- **Aliases that contain `/`**: the alias is part of the URL path, so such requests match no endpoint |
| 124 | + |
| 125 | +## Alert Key |
| 126 | +--- |
| 127 | + |
| 128 | +The request's `alias` is the Alert Key. Opsgenie defines alias as the "client-defined identifier of the alert, that is also the key element of Alert De-Duplication" ([Alert API](https://docs.opsgenie.com/docs/alert-api#create-alert)). Create requests with the same alias merge into one alert, and a Close request recovers that alert by alias. Alertmanager and Grafana both use a hash of the alert group as the alias, which stays the same from trigger to recovery. |
| 129 | + |
| 130 | +Without `alias`, every Create request opens a new alert that no Close request can recover. |
| 131 | + |
| 132 | +## Field mapping |
| 133 | +--- |
| 134 | + |
| 135 | +| Opsgenie field | In Flashduty | |
| 136 | +| :--- | :--- | |
| 137 | +| `message` (required) | Alert title, label `check` | |
| 138 | +| `description` | Alert description | |
| 139 | +| `alias` | Alert Key, label `alias` | |
| 140 | +| `priority` | Severity, label `priority` | |
| 141 | +| `entity` | Labels `entity` and `resource` | |
| 142 | +| `source` | Label `source` | |
| 143 | +| `details` | One label per key-value pair | |
| 144 | +| `tags` | `key:value` tags become labels of the same name; other tags are joined with commas in the label `tags` | |
| 145 | + |
| 146 | +`responders`, `visibleTo`, `actions`, `user` and `note` are ignored; assignment and notifications follow the Flashduty channel's settings. |
| 147 | + |
| 148 | +## Severity |
| 149 | +--- |
| 150 | + |
| 151 | +| Opsgenie `priority` | Flashduty severity | |
| 152 | +| :--- | :--- | |
| 153 | +| `P1`, `P2` | Critical | |
| 154 | +| `P3`, empty | Warning | |
| 155 | +| `P4`, `P5` | Info | |
| 156 | + |
| 157 | +Any other value returns 422. Recovery comes from the Close request, not from `priority`. |
| 158 | + |
| 159 | +## Troubleshooting |
| 160 | +--- |
| 161 | + |
| 162 | +- **404**: the Alertmanager `api_url` is missing the trailing `/`, or the Grafana Alert API URL is missing `/v2/alerts` |
| 163 | +- **401**: the `integration_key` in the push URL is wrong, or the integration is disabled |
| 164 | +- **422**: `message` is empty, `priority` is not between `P1` and `P5`, or the Close request does not use `identifierType=alias`; it is also returned when the `integration_key` in the push URL belongs to an integration of another type |
| 165 | +- **The alert does not recover**: make sure Alertmanager has `send_resolved: true` and Grafana has **Auto close incidents** selected |
0 commit comments