4 Webhook

概述

webhook 媒介类型可用于使用自定义 JavaScript 代码发起 HTTP 调用，从而与帮助台系统、聊天工具或即时通讯软件等外部软件进行直接集成。 您可以选择导入由 Zabbix 提供的集成，或从头开始创建自定义集成。

集成

以下集成可用，允许使用预定义的 webhook 媒介类型将 Zabbix 通知推送到：

除这里列出的服务外，Zabbix 还可以与 Spiceworks 集成（无需 webhook）。 要将 Zabbix 通知转换为 Spiceworks 工单，请创建一个电子邮件媒介类型，并在指定 Zabbix 用户的配置文件设置中输入 Spiceworks 服务台电子邮件地址（例如 help\@zabbix.on.spiceworks.com）。

配置

要开始使用 webhook 集成：

  1. 在已下载的 Zabbix 版本的 templates/media 目录中找到所需的 .yaml 文件，或从 Zabbix git repository 下载。
  2. 将该文件导入到您的 Zabbix 安装中。
    webhook 将出现在媒介类型列表中。
  3. 根据 Readme.md 文件中的说明配置 webhook（您可以点击上方的 webhook 名称以快速访问 Readme.md）。

要从头创建自定义 webhook：

  1. 前往 报警 > 媒介类型。
  2. 点击 创建媒介类型。

媒介类型 选项卡包含此媒介类型特有的各种属性：

所有必填输入字段都以红色星号标记。

以下参数是 webhook 媒介类型特有的：

参数 描述
参数 将 webhook 变量指定为属性和值对。
对于预配置的 webhook，参数列表因服务而异。请查看 webhook 的 Readme.md 文件了解参数说明。
对于新的 webhook，默认包含几个常见变量（URL:<empty>、HTTPProxy:<empty>、To:{ALERT.SENDTO}、Subject:{ALERT.SUBJECT}、Message:{ALERT.MESSAGE}），您可以保留或删除它们。

Webhook 参数支持用户宏、问题通知中支持的所有宏，以及额外支持的 {ALERT.SENDTO}、{ALERT.SUBJECT} 和 {ALERT.MESSAGE} 宏。

如果您指定了 HTTP proxy，该字段支持与监控项配置中的 HTTP proxy 字段相同的功能。proxy 字符串可以带有 [scheme]:// 前缀，以指定所使用的 proxy 类型（例如 https、socks4、socks5；请参见文档）。
脚本 在参数字段中点击或点击其旁边的铅笔图标时，会打开模态编辑器；请在其中输入 JavaScript 代码。此代码将执行 webhook 操作。
该脚本是接受参数-值对的函数代码。应使用 JSON.parse() 方法将值转换为 JSON 对象，例如：var params = JSON.parse(value);。

代码可以访问所有参数，能够执行 HTTP GET、POST、PUT 和 DELETE 请求，支持 CONNECT、PATCH、HEAD、OPTIONS 和 TRACE 等附加方法，并可控制 HTTP 标头和请求正文。
脚本必须包含 return 运算符，否则将无效。它可以返回 OK 状态以及可选的标签和值列表（请参见 处理标签 选项），或者返回错误字符串。

恢复事件（无论是自动生成还是手动关闭产生）由服务器创建，并包含已解析的事件标签（包括从模板、主机和触发器继承的标签）。Webhook 脚本会在报警创建后执行；因此，webhook 脚本返回的标签仅会在初始报警创建之后添加，不会出现在初始问题消息或即时恢复消息的 {EVENT.TAGS} 和 {EVENT.RECOVERY.TAGS} 宏中。
注意：建议使用局部变量（例如 var local = 1）而不是全局变量（例如 global = 1），以确保每个脚本都基于自己的数据运行，并避免并发调用之间发生冲突（请参见已知问题）。

另请参见：Webhook development guidelines、Webhook script examples、Additional JavaScript objects。
超时 JavaScript 执行超时（1-60 秒，默认 30 秒）。
支持时间后缀，例如 30s、1m。
处理标签 勾选此复选框可将返回的 JSON 属性值作为标签处理。这些标签会添加到任何现有的问题标签中。
请注意，使用 webhook tags 时，webhook 必须返回一个至少包含空 tags 对象的 JSON 对象：var result = {tags: {}};
可返回的标签示例：jira-id:prod-1234、responsible:John Smith、processed:<no value>
包含事件菜单项 勾选此复选框可在事件菜单中包含一个条目，链接到已创建的外部工单。
对于每个已启用且勾选了此复选框的 webhook，都会包含一个条目。请注意，如果 菜单项名称 和 菜单项 URL 参数包含任何 {EVENT.TAGS.<tag name>} 宏，则只有在这些宏可以被解析时才会包含该条目（即事件已定义这些标签）。
如果勾选，不应将该 webhook 用于向不同用户发送通知（建议改为创建专用用户），也不应在单个问题事件的多个报警动作中使用。
菜单项名称 指定菜单项名称。
支持 {EVENT.TAGS.<tag name>} 宏。
仅当勾选了 包含事件菜单项 时，此字段才是必填项。
菜单项 URL 指定菜单项的底层 URL。
支持 {EVENT.TAGS.<tag name>} 宏。
仅当勾选了 包含事件菜单项 时，此字段才是必填项。

有关如何配置默认消息和报警处理选项的详细信息，请参见通用媒介类型参数。

即使 webhook 不使用默认消息，仍必须为该 webhook 使用的操作类型定义消息模板。

测试

要测试已配置的 webhook 媒介类型：

  1. 在媒介类型列表中找到相应的 webhook。
  2. 单击列表最后一列中的 Test（将打开一个测试窗口）。
  3. 根据需要编辑 webhook 参数值。
    将宏替换为示例值；否则宏将无法解析，测试将失败。
  4. 单击 Test。

在测试窗口中替换或删除值只会影响测试过程，实际的 webhook 属性值将保持不变。

要在不离开测试窗口的情况下查看媒介类型测试日志条目，请单击 Open log（将打开一个新的弹出窗口）。

如果 webhook 测试成功：

  • 将显示 “Media type test successful.” 消息。
  • 服务器响应将显示在灰色的 Response 字段中。
  • Response 字段下方会标明响应类型（JSON 或 String）。

如果 webhook 测试失败：

  • 将显示 “Media type test failed.” 消息，后跟其他失败详情。

用户介质

配置好介质类型后，前往 Users > Users 部分，将 webhook 介质分配给现有用户，或创建一个新用户来代表该 webhook。 为现有用户设置用户介质的步骤对所有介质类型都相同，详见介质类型页面。

如果 webhook 使用标签来存储工单\消息 ID，应避免将同一个 webhook 作为介质分配给不同用户，否则可能导致 webhook 错误（这适用于大多数使用 Include event menu entry 选项的 webhook）。 在这种情况下，最佳实践是创建一个专用用户来代表该 webhook：

  1. 配置好 webhook 介质类型后，前往 Users > Users 部分，创建一个专用的 Zabbix 用户来代表该 webhook——例如，为 Slack webhook 创建用户名为 Slack 的用户。
    除介质外，所有设置都可以保留默认值，因为该用户不会登录 Zabbix。
  2. 在用户配置文件中，前往 Media 选项卡，并添加 webhook，填写所需的联系信息。
    如果 webhook 不使用 Send to 字段，请输入任意受支持字符的组合以绕过验证要求。
  3. 为该用户授予至少对所有需要发送告警的主机的读权限。

配置告警动作时，在操作详情中的 Send to users 字段添加此用户——这将告知 Zabbix 对此动作的通知使用该 webhook。

配置告警动作

动作决定了应通过 webhook 发送哪些通知。 涉及 webhook 的配置动作步骤与所有其他媒介类型相同，但以下情况除外：

  • 如果 webhook 使用 webhook 标签 来存储工单\消息 ID 并处理更新\解决操作，请避免在单个问题事件中于多个告警动作中使用同一个 webhook。 如果存在 {EVENT.TAGS.<tag name>} 且该值在 webhook 中被更新，则其结果值将是未定义的。 为避免这种情况，请在 webhook 中使用新的标签名称来存储更新后的值。 这适用于 Zabbix 提供的 Jira、Jira Service Desk、Mattermost、Opsgenie、OTRS、Redmine、ServiceNow、Slack、Zammad 和 Zendesk webhook，以及大多数使用 Include event menu entry 选项的 webhook。 但请注意，单个 webhook 可以在同一动作的多个操作或升级步骤中使用，也可以在不同动作中使用，只要这些动作不会因不同的条件而被同一个问题事件触发。
  • 在针对内部事件的动作中使用 webhook 时，请确保勾选 Custom message 复选框，并在动作操作配置中定义自定义消息。 否则，将不会发送通知。