4 Webhook

概述

Webhook媒体类型适用于使用自定义JavaScript代码进行HTTP调用，以便与外部软件（如帮助台系统、聊天工具或即时通讯软件）实现直接集成。 您可以选择importZabbix提供的集成方案，或create从头开始创建自定义集成方案。

集成

以下集成可用于通过预定义的 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 仓库 下载。
  2. 将该文件 导入 到您的 Zabbix 安装中。 webhook 将显示在媒体类型列表中。
  3. 按照 Readme.md 文件中的说明配置 webhook（您可以点击上方某个 webhook 的名称，快速访问 Readme.md）。

要从零开始创建自定义 webhook：

  1. 转到 告警 > 媒体类型。
  2. 点击 创建媒体类型。

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

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

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

Parameter Description
Parameters 将 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 代理，该字段支持与监控项配置中的 HTTP proxy 字段相同的功能。代理字符串前可以加上 [scheme]:// 前缀，以指定所使用的代理类型（例如 https、socks4、socks5；参见 文档）。
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），以确保每个脚本都操作自己的数据，并避免同时调用时发生冲突（参见 已知问题）。

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

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

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

测试

测试配置的webhook媒体类型：

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

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

要查看媒体类型测试日志条目而不离开测试窗口，点击Open log（将打开一个新的弹出窗口）。

如果webhook测试成功：

  • 显示"媒体类型测试成功。"消息。
  • 服务器响应出现在灰色的响应字段中。
  • 响应类型（JSON或string）在响应字段下方指定。

如果Webhook测试失败：

  • 显示"媒体类型测试失败。"消息，随后附上其他失败详情。

用户媒体

配置好媒体类型后，转到 Users > Users 部分，将 webhook 媒体分配给现有用户，或者创建一个新用户来代表该 webhook。 关于为现有用户设置用户媒体的步骤（这些步骤对所有媒体类型都通用），请参见 Media types 页面。

如果某个 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. 为该用户授予至少对所有应发送告警的主机的只读权限。

配置告警动作时，在 Operation details 中的 Send to users 字段添加该用户 - 这将告诉 Zabbix 使用该 webhook 发送此动作的通知。

配置告警动作

操作决定了应通过webhook发送哪些通知。 涉及webhook的configuring actions步骤与其他所有媒介类型相同，但存在以下例外情况：

  • 如果webhook使用webhook tags存储票据/消息ID并处理update\解决操作，请避免在单个问题事件的多个警报操作中使用相同的webhook。 如果{EVENT.TAGS.<tag name>}存在并在webhook中更新，其最终值将变为未定义。 为避免这种情况，请在webhook中使用新的标签名称来存储更新后的值。 这适用于Zabbix提供的Jira、Jira Service Desk、Mattermost、Opsgenie、OTRS、Redmine、ServiceNow、Slack、Zammad和Zendesk webhook，以及大多数使用包含事件菜单项选项的webhook。 但请注意，单个webhook可以在同一操作的多个操作或升级步骤中使用，也可以在不同操作中使用，这些操作由于不同的conditions而不会被同一问题事件触发。
  • 在内部事件的操作中使用webhook时，请确保勾选自定义消息复选框，并在操作配置中定义自定义消息。 否则，将不会发送通知。