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. 点击创建媒体类型。
  3. 在表单中输入 webhook 媒体类型参数。

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

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

以下参数是 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 开发指南、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. 单击列表最后一列中的测试（将打开测试窗口）。
  3. 根据需要编辑 webhook 参数值。
    将宏替换为示例值；否则，宏将无法解析，测试也会失败。
  4. 单击测试。

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

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

如果 webhook 测试成功：

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

如果 webhook 测试失败：

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

用户媒体

配置媒体类型后，转到 用户 > 用户 部分，将 webhook 媒体分配给现有用户，或创建一个代表该 webhook 的新用户。 为现有用户设置用户媒体的步骤适用于所有媒体类型，详见媒体类型页面。

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

  1. 配置 webhook 媒体类型后，转到 用户 > 用户 部分，创建一个专用的 Zabbix 用户来代表该 webhook - 例如，为 Slack webhook 创建用户名为 Slack 的用户。 除媒体以外的所有设置均可保留默认值，因为该用户不会登录 Zabbix。
  2. 在用户配置文件中，转到 媒体 选项卡，并添加 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 webhooks，以及大多数使用 Include event menu entry 选项的 webhooks。 不过请注意，同一个 webhook 可以在同一动作的多个操作或升级步骤中使用，也可以用于不同的动作，只要这些动作不会因不同的条件而由同一个问题事件触发。
  • 在针对内部事件的动作中使用 webhook 时，请确保勾选 Custom message 复选框，并在动作操作配置中定义自定义消息。 否则，将不会发送通知。