菜单

Webhook

Grafana Cloud 企业版开源

配置 Webhook 通知

在联系点中使用 Webhook 集成将告警通知发送到您的 Webhook。

Webhook 集成是一种灵活的方式，可以将告警集成到您的系统中。当通知触发时，它会向 Webhook 端点发送一个包含告警详细信息和附加数据的 JSON 请求。

配置联系点的 Webhook

要创建具有 Webhook 集成的联系点，请完成以下步骤。

导航到 告警和 IRM -> 告警 -> 联系点。
点击 + 添加联系点。
输入联系点的名称。
从集成列表中，选择 Webhook。
在 URL 字段中，复制您的 Webhook URL。
(可选) 配置附加设置。
点击 保存联系点。

有关联系点的更多详细信息，包括如何测试和启用通知，请参阅配置联系点。

Webhook 设置

选项	描述
URL	Webhook URL。

可选设置

选项	描述
HTTP 方法	指定使用的 HTTP 方法：`POST` 或 `PUT`。
基本认证用户名	HTTP 基本认证的用户名。
基本认证密码	HTTP 基本认证的密码。
认证 Header Scheme	`Authorization` 请求头的 Scheme。默认是 `Bearer`。
认证 Header Credentials	`Authorization` 请求头的 Credentials。
额外 Headers	请求中包含的附加 HTTP 头。
最大告警数	通知中包含的最大告警数。超出此限制的任何告警将被忽略。`0` 表示无限制。
TLS	TLS 配置选项，包括 CA 证书、客户端证书和客户端密钥。
HMAC 签名	HMAC 签名配置选项。

注意
您可以配置 HTTP 基本认证或 Authorization 请求头中的任意一种，但不能同时配置两者。

HMAC 签名

您可以使用 HMAC 签名来保护您的 Webhook 通知，以验证请求的真实性和完整性。启用后，Grafana 会使用共享密钥通过 HMAC-SHA256 对 Webhook 有效载荷进行签名。

选项	描述
密钥	用于生成 HMAC 签名的共享密钥。
Header	设置签名的 HTTP 头。默认是 `X-Grafana-Alerting-Signature`。
时间戳 Header	可选的 header，用于在签名计算中包含时间戳。指定后，Grafana 将在此 header 中设置一个 Unix 时间戳，并将其包含在 HMAC 计算中。这可以防止重放攻击。

配置 HMAC 签名后，Grafana 会使用您的密钥通过 HMAC-SHA256 生成签名。如果指定了时间戳 header，则签名计算中会包含一个 Unix 时间戳。签名计算方式如下：

HMAC(timestamp + ":" + body)

时间戳会发送到指定的 header 中。如果没有指定时间戳 header，签名仅根据请求体计算。签名会作为十六进制编码字符串发送到指定的签名 header 中。

验证请求

要验证来自 Grafana 的入站 Webhook 请求，请按照以下步骤操作：

从 header 中提取签名（默认是 X-Grafana-Alerting-Signature）。
如果您配置了时间戳 header，提取时间戳值并验证其是否最近，以防止重放攻击。
计算预期签名
- 使用您的共享密钥创建一个 HMAC-SHA256 哈希
- 如果使用时间戳，在请求体之前包含时间戳，后跟一个冒号 (:)
- 对原始请求体进行哈希计算
- 将结果转换为十六进制字符串
将计算出的签名与请求 header 中的签名进行比较。

使用模板的可选设置

使用以下设置在JSON 有效载荷中包含自定义数据。这两个选项都支持使用通知模板。

选项	描述
标题	将值作为字符串发送到JSON 有效载荷的 `title` 字段中。支持通知模板。
消息	将值作为字符串发送到JSON 有效载荷的 `message` 字段中。支持通知模板。
自定义有效载荷	可选地使用自定义模板覆盖默认有效载荷格式。

可选通知设置

选项	描述
禁用解决消息	启用此选项可在告警解决时阻止通知。

默认 JSON 有效载荷

以下示例显示了包含两个触发告警信息的 Webhook 通知有效载荷

{
  "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": "",
      "values": {
        "B": 44.23943737541908,
        "C": 1
      }
    },
    {
      "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": "",
      "values": {
        "B": 44.23943737541908,
        "C": 1
      }
    }
  ],
  "groupLabels": {},
  "commonLabels": {
    "team": "blue"
  },
  "commonAnnotations": {},
  "externalURL": "https://play.grafana.org/",
  "version": "1",
  "groupKey": "{}:{}",
  "truncatedAlerts": 0,
  "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 通知中的 JSON 有效载荷包含以下键值对

键	类型	描述
`receiver`	string	联系点的名称。
`status`	string	告警的当前状态，`firing` (触发) 或 `resolved` (已解决)。
`orgId`	number	与有效载荷相关的组织 ID。
`alerts`	告警数组	正在触发的告警。
`groupLabels`	object	用于分组的标签，字符串键到字符串值的映射。
`commonLabels`	object	所有告警共有的标签，字符串键到字符串值的映射。
`commonAnnotations`	object	所有告警共有的标注，字符串键到字符串值的映射。
`externalURL`	string	发送此 Webhook 的 Grafana 实例的外部 URL。
`version`	string	有效载荷结构的版本。
`groupKey`	string	用于分组的键。
`truncatedAlerts`	number	被截断的告警数量。
`state`	string	告警组的状态（`alerting` 或 `ok`）。

以下键值对也包含在 JSON 有效载荷中，并可以使用通知模板在 Webhook 设置中进行配置。

键	类型	描述
`title`	string	自定义标题。可在Webhook 设置中使用通知模板进行配置。
`message`	string	自定义消息。可在Webhook 设置中使用通知模板进行配置。

Alert

Alert 对象表示通知组中包含的一个告警，由alerts 字段提供。

键	类型	描述
`status`	string	告警的当前状态，`firing` (触发) 或 `resolved` (已解决)。
`labels`	object	此告警的标签，字符串键到字符串值的映射。
`annotations`	object	此告警的标注，字符串键到字符串值的映射。
`startsAt`	string	告警开始时间。
`endsAt`	string	告警结束时间，未解决时的默认值为 `0001-01-01T00:00:00Z`。
`values`	object	触发当前状态的值。
`generatorURL`	string	Grafana UI 中告警规则的 URL。
`fingerprint`	string	标签指纹，具有相同标签的告警将拥有相同的指纹。
`silenceURL`	string	在 Grafana UI 中静默此告警规则的 URL。
`dashboardURL`	string	如果告警具有 Dashboard UID 标注，则指向 Grafana 仪表盘的链接。
`panelURL`	string	如果告警具有 Panel ID 标注，则指向面板的链接。
`imageURL`	string	创建此通知的规则所关联的面板的屏幕截图 URL。

自定义有效载荷

“自定义有效载荷”选项允许您使用模板完全自定义 Webhook 有效载荷。这使您可以完全控制 Webhook 请求的结构和内容。

选项	描述
有效载荷模板	定义 Webhook 有效载荷结构的模板字符串。
有效载荷变量	定义在模板中 `.Vars.<variable_name>` 下可用的附加变量的键值对。

包含变量的自定义有效载荷模板示例

{
  "alert_name": "{{ .CommonLabels.alertname }}",
  "status": "{{ .Status }}",
  "environment": "{{ .Vars.environment }}",
  "custom_field": "{{ .Vars.custom_field }}"
}

注意
使用“自定义有效载荷”时，标题和消息字段将被忽略，因为整个有效载荷结构由您的模板决定。

JSON 模板函数

创建自定义有效载荷时，可以使用多个模板函数来帮助生成有效的 JSON 结构。这些函数包括用于创建字典 (coll.Dict)、数组 (coll.Slice, coll.Append) 以及在 JSON 字符串和对象之间进行转换 (data.ToJSON, data.JSON) 的函数。有关这些函数和其他模板函数的详细信息，请参阅通知模板函数。

有关这些函数和其他模板函数的详细信息，请参阅通知模板函数。

使用 JSON 助手函数示例

{{ define "webhook.custom.payload" -}}
  {{ coll.Dict
  "receiver" .Receiver
  "status" .Status
  "alerts" (tmpl.Exec "webhook.custom.simple_alerts" .Alerts | data.JSON)
  "groupLabels" .GroupLabels
  "commonLabels" .CommonLabels
  "commonAnnotations" .CommonAnnotations
  "externalURL" .ExternalURL
  "version" "1"
  "orgId"  (index .Alerts 0).OrgID
  "truncatedAlerts"  .TruncatedAlerts
  "groupKey" .GroupKey
  "state"  (tmpl.Inline "{{ if eq .Status \"resolved\" }}ok{{ else }}alerting{{ end }}" . )
  "allVariables"  .Vars
  "title" (tmpl.Exec "default.title" . )
  "message" (tmpl.Exec "default.message" . )
  | data.ToJSONPretty " "}}
{{- end }}

{{- /* Embed json templates in other json templates. */ -}}
{{ define "webhook.custom.simple_alerts" -}}
  {{- $alerts := coll.Slice -}}
  {{- range . -}}
    {{ $alerts = coll.Append (coll.Dict
    "status" .Status
    "labels" .Labels
    "startsAt" .StartsAt
    "endsAt" .EndsAt
    ) $alerts}}
  {{- end -}}
  {{- $alerts | data.ToJSON -}}
{{- end }}