diff --git a/docs/sources/alerting/unified-alerting/contact-points.md b/docs/sources/alerting/unified-alerting/contact-points.md index 63f5a5602a9..61ba3029a88 100644 --- a/docs/sources/alerting/unified-alerting/contact-points.md +++ b/docs/sources/alerting/unified-alerting/contact-points.md @@ -60,6 +60,127 @@ Grafana alerting UI allows you to configure contact points for the Grafana manag | [Webhook](#webhook) | `webhook` | | [Zenduty](#zenduty) | `webhook` | +## Webhook + +Example JSON body: + +```json +{ + "receiver": "My Super Webhook", + "status": "firing", + "orgId": 1, + "alerts": [ + { + "status": "firing", + "labels": { + "alertname": "High memory usage", + "team": "blue", + "zone": "us-1" + }, + "annotations": { + "description": "The system has high memory usage", + "runbook_url": "https://myrunbook.com/runbook/1234", + "summary": "This alert was triggered for zone us-1" + }, + "startsAt": "2021-10-12T09:51:03.157076+02:00", + "endsAt": "0001-01-01T00:00:00Z", + "generatorURL": "https://play.grafana.org/alerting/1afz29v7z/edit", + "fingerprint": "c6eadffa33fcdf37", + "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1", + "dashboardURL": "", + "panelURL": "", + "valueString": "[ metric='' labels={} value=14151.331895396988 ]" + }, + { + "status": "firing", + "labels": { + "alertname": "High CPU usage", + "team": "blue", + "zone": "eu-1" + }, + "annotations": { + "description": "The system has high CPU usage", + "runbook_url": "https://myrunbook.com/runbook/1234", + "summary": "This alert was triggered for zone eu-1" + }, + "startsAt": "2021-10-12T09:56:03.157076+02:00", + "endsAt": "0001-01-01T00:00:00Z", + "generatorURL": "https://play.grafana.org/alerting/d1rdpdv7k/edit", + "fingerprint": "bc97ff14869b13e3", + "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1", + "dashboardURL": "", + "panelURL": "", + "valueString": "[ metric='' labels={} value=47043.702386305304 ]" + } + ], + "groupLabels": {}, + "commonLabels": { + "team": "blue" + }, + "commonAnnotations": {}, + "externalURL": "https://play.grafana.org/", + "version": "1", + "groupKey": "{}:{}", + "truncatedAlerts": 0, + "orgId": 1, + "title": "[FIRING:2] (blue)", + "state": "alerting", + "message": "**Firing**\n\nLabels:\n - alertname = T2\n - team = blue\n - zone = us-1\nAnnotations:\n - description = This is the alert rule checking the second system\n - runbook_url = https://myrunbook.com\n - summary = This is my summary\nSource: https://play.grafana.org/alerting/1afz29v7z/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1\n\nLabels:\n - alertname = T1\n - team = blue\n - zone = eu-1\nAnnotations:\nSource: https://play.grafana.org/alerting/d1rdpdv7k/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1\n" +} +``` + +### Webhook fields + +#### Body + +| Key | Type | Description | +| ----------------- | ------------------------- | ------------------------------------------------------------------------------- | +| receiver | string | Name of the webhook | +| status | string | Current status of the alert, `firing` or `resolved` | +| orgId | number | ID of the organization related to the payload | +| alerts | array of [alerts](#alert) | Alerts that are triggering | +| groupLabels | object | Labels that are used for grouping, map of string keys to string values | +| commonLabels | object | Labels that all alarms have in common, map of string keys to string values | +| commonAnnotations | object | Annotations that all alarms have in common, map of string keys to string values | +| externalURL | string | External URL to the Grafana instance sending this webhook | +| version | string | Version of the payload | +| groupKey | string | Key that is used for grouping | +| truncatedAlerts | number | Number of alerts that were truncated | +| title | string | **Will be deprecated soon** | +| state | string | **Will be deprecated soon** | +| message | string | **Will be deprecated soon** | + +#### Alert + +| Key | Type | Description | +| ------------ | ------ | ---------------------------------------------------------------------------------- | +| status | string | Current status of the alert, `firing` or `resolved` | +| labels | object | Labels that are part of this alert, map of string keys to string values | +| annotations | object | Annotations that are part of this alert, map of string keys to string values | +| startsAt | string | Start time of the alert | +| endsAt | string | End time of the alert, default value when not resolved is `0001-01-01T00:00:00Z` | +| valueString | string | Values that triggered the current status | +| generatorURL | string | URL of the alert rule in the Grafana UI | +| fingerprint | string | The labels fingerprint, alarms with the same labels will have the same fingerprint | +| silenceURL | string | URL to silence the alert rule in the Grafana UI | +| dashboardURL | string | **Will be deprecated soon** | +| panelURL | string | **Will be deprecated soon** | + +### Breaking changes when updating to unified alerting + +Grafana 8 alerts introduce a new way to manage your alerting rules and alerts in Grafana. +As part of this change, there are some breaking changes that we will explain in details. + +#### Multiple Alerts in one payload + +As we now enable [multi dimensional alerting]({{< relref "../difference-old-new.md#multi-dimensional-alerting" >}}) a payload +consists of an array of alerts. + +#### Removed fields related to dashboards + +Alerts are not coupled to dashboards anymore therefore the fields related to dashboards `dashboardId` and `panelId` have been removed. +where removed. The removed fields are `dashboardId` and `panelId`. + ## Manage contact points for an external Alertmanager Grafana alerting UI supports managing external Alertmanager configuration. Once you add an [Alertmanager data source]({{< relref "../../datasources/alertmanager.md" >}}), a dropdown displays at the top of the page where you can select either `Grafana` or an external Alertmanager as your data source.