4 Webhook

4 Webhook

概述

webhook 媒体类型对于使用自定义的JavaScript代码进行HTTP调用非常有用，它可以直接与外部软件（如 Helpdesk 系统、聊天工具或信使）进行集成。您可以选择使用 Zabbix 提供的集成方式或创建一个自定义集成方式。

集成

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

除了此处列出的服务外，Zabbix 还可以与 Spiceworks 集成（无需 webhook）。要将 Zabbix 通知转换为 Spiceworks 票证，请创建电子邮件媒体类型并在指定 Zabbix 用户的配置文件设置中输入 Spiceworks 帮助台电子邮件地址（例如 [email protected]）。

配置

开始使用webhook集成:

在已下载的 Zabbix 的 templates/media目录中，找到所需的.xml文件；或者从Zabbix的 git仓库中下载
将文件导入到 Zabbix 安装，Webhook 将出现在媒体类型列表中。
根据 Readme.md 文件中的说明来配置 webhook （也可以点击 webhook’s 名称来快速访问 Readme.md ）。

从零开始创建一个自定义的webhook:

进入告警 → 媒介类型
点击创建媒介类型

媒介类型选项卡包含了针对这种媒介类型的各种属性:

红色星号标记的为必填字段。

webhook媒介类型的具体参数如下:

参数	说明
参数	webhook变量作为属性和值对。对于预先配置的webhook，参数列表会随着服务的不同而变化。检查webhook的Readme.md 参数说明文件。对于新的webhooks，默认情况下包含了几个常见的变量 (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}), 你可以保留或删除它们。参数中支持问题通知中支持的所有宏如果指定了HTTP Proxy，该字段支持与监控项配置HTTP proxy字段相同的功能。 Proxy字符串可以加上前缀 `[scheme]://` 来指定使用哪种代理例如https, socks4, socks5; 请参见documentation).
脚本	在点击参数字段(或旁边的查看/编辑按钮)时出现的块中输入JavaScript代码。这段代码将执行webhook操作。脚本是接受参数-值对的一段功能代码，它的值应该使用JSON.parse() 方法转换为JSON对象，例如：`var params = JSON.parse(value);`. 代码可以访问所有参数，它可以执行HTTP GET、POST、PUT和DELETE请求，并可控制HTTP头和请求正文。脚本必须包含一个返回值，否则它将无效。它可以返回OK状态以及一个可选的标签列表，标签值(参见Process tags选项)，或一个错误的字符串。注意，脚本只有在创建警报之后才会执行。如果脚本被配置为返回和处理标签 (参见处理标签选项),这些标签将不会在初始问题消息和恢复消息中的 {EVENT.TAGS} 和 {EVENT.RECOVERY.TAGS} 宏中解析，因为脚本还没有时间运行。另请参阅： Webhook开发指南, Webhook脚本样例, 额外的 JavaScript 对象.
超时	JavaScript执行超时 (1-60s, 默认为30s)。支持时间后缀, 例如 30s, 1m。
处理标签	选中复选框标以将返回的JSON属性值作为标签处理。这些标签将被添加到Zabbix中已经存在的(如果有的话)问题事件标签中。如果webhook使用了标签(Process tags复选框被选中),webhook应该返回一个至少带有一个空标签的JSON对象`var result = {tags: {}};`. 返回的标签示例: Jira ID: PROD-1234, Responsible: John Smith, Processed:<no value>, 等.
包括事件菜单项	选中复选框以在事件菜单中包含一个链接到创建的外部目标的条目。若选中此项，webhook就不应该被用来向不同的用户发送通知 (考虑创建一个专有用户) 或者在几个告警动作中关联单个问题事件.
菜单项名称	指定菜单入口名称。支持{EVENT.TAGS.<tag name>}宏只有当包括事件菜单项被选中时，该字段才为必填项。
菜单项URL	指定菜单入口的URL。支持{EVENT.TAGS.<tag name>} 宏只有当包括事件菜单项被选中时，该字段才为必填项。

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

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

媒体类型测试

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

在媒体类型列表中找到相关的 webhook。
单击列表最后一列中的测试（将打开一个测试窗口）。
如果需要，编辑 webhook 参数值。
单击测试。

默认情况下，webhook 测试使用配置期间输入的参数执行。但是，可以更改测试的属性值。在测试窗口中替换或删除值只会影响测试过程，实际的 webhook 属性值将保持不变。

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

如果 webhook 测试成功：

显示“媒体类型测试成功。”消息。
服务器响应显示在灰色的“响应”字段中。
响应类型（JSON 或字符串）在“响应”字段下方指定。

如果 webhook 测试失败：

显示“媒体类型测试失败。”消息，随后显示其他失败详细信息。

用户媒介

媒介类型配置完成后，前往 用户 → 用户 部分，为一个现有用户或创建一个新用户并指定其webhook媒介。关于如何为用户指定用户媒介的方式和指定其它媒介类型类似，具体请参见媒介类型。

如果webhook使用标签来存储 ticket\message ID, 避免将同一个 webhook 作为媒体分配给不同的用户，因为这样做可能会导致webhook错误 (适用于大多数使用了 Include event menu entry 选项)。在这种情况下，最好的做法是创建一个专用的用户来表示webhook:

配置好webhook媒体类型后，前往 用户→ 用户 部分，并创建一个专用的Zabbix用户来表示webhook - 例如, 为 Slack webhook添加一个别名 Slack。所有的设置可以保持默认值（除了媒体），因为这个用户不会登录到Zabbix。
在用户配置中，进入Media 选项卡并且填写 add a webhook 所需的联系信息。如果webhook没有使用Send to 字段, 可以输入任何支持的字符组合来绕过验证要求。
至少授予该用户对要向其发送警报的所有主机有可读的权限。

配置告警动作时，请在Send to users字段中添加该用户 - 这将告诉Zabbix使用webhook来获取来自这个动作的通知。

配置告警动作

告警动作决定了哪些通知应该通过webhook发送。webhook的configuring actions 步骤与所有其他媒体类型相同，但有以下例外:

如果webhook使用标签来存储 ticket\message ID 以及后续的 update\resolve operations 操作, 这个webhook不应该用于单个问题事件的多个告警动作中。这适用于Zabbix提供的Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad和Zendesk webhooks以及大多数使用 Include event menu entry 选项的webhook。如果操作或升级步骤属于同一个动作，允许在多个操作中使用webhook。在不同的动作中使用webhook也是可以的，由于不同的筛选器条件，动作不会应用到相同的问题事件中。
当在动作中使用webhook用于 internal events: 在动作操作配置中，选中 Custom message复选框，输入自定义消息内容，否则通知不会被发送出去。