4 Webhook

概述

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

集成

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

除了此处列出的服务外，Zabbix 还可以与 Spiceworks 集成（无需 webhook）。 要将 Zabbix 通知转换为 Spiceworks 工单，请创建一个 email media type，并在指定 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. 转到 Alerts > Media types。
  2. 点击 Create media type。

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

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

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

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

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

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

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

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

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

有关如何配置默认消息和告警处理选项的详细信息，请参见 common media type parameters。

即使 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 复选框，并在动作操作配置中定义自定义消息。 否则，将不会发送通知。