4 Webhook

概述

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

集成

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

除了此处列出的服务外，Zabbix 还可以与 Spiceworks 集成（无需 webhook）。 要将 Zabbix 通知转换为 Spiceworks 工单，请创建一个 email media type，并在指定 Zabbix 用户的个人资料设置中输入 Spiceworks 帮助台电子邮件地址（例如 [email protected]）。

配置

要开始使用 webhook 集成：

  1. 在下载的 Zabbix 版本的 templates/media 目录中找到所需的 .yaml 文件，或从 Zabbix git 仓库下载。
  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 状态以及可选的标签和标签值列表（请参阅处理标签选项），也可以返回错误字符串。

请注意，脚本仅在创建告警后执行。如果脚本配置为返回并处理标签，则初始问题消息和恢复消息中的 {EVENT.TAGS} 和 {EVENT.RECOVERY.TAGS} 宏不会解析这些标签，因为脚本尚未有时间运行。
注意：建议使用局部变量（例如 var local = 1），而不是全局变量（例如 global = 1），以确保每个脚本仅操作自身的数据，并避免同时调用之间发生冲突（请参阅已知问题）。

另请参阅：Webhook 开发指南、Webhook 脚本示例、其他 JavaScript 对象。
超时 JavaScript 执行超时时间（1-60 秒，默认 30 秒）。
支持时间后缀（例如 30s、1m）。
处理标签 选中复选框，将返回的 JSON 属性值作为标签进行处理。这些标签会添加到现有的问题标签中。
请注意，使用 webhook 标签时，webhook 必须返回一个至少包含空标签对象的 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.” 消息，后跟其他失败详情。

用户介质

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

如果 webhook 使用标签来存储工单\消息 ID，请避免将同一个 webhook 作为介质分配给不同用户，因为这样做可能会导致 webhook 错误（适用于大多数使用 包含事件菜单项 选项的 webhook）。
在这种情况下，最佳实践是创建一个专用用户来代表该 webhook：

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

配置告警动作时，在操作详情的 发送到用户 字段中添加该用户——这将告知 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 复选框，并在动作操作配置中定义自定义消息。 否则，将不会发送通知。