4 Webhook

概述

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

集成

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

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

配置

开始使用webhook集成:

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

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

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

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

4 Webhook - 图1

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

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 媒体类型:

  1. 在媒体类型 列表 中找到相关的 webhook。

  2. 单击列表最后一列中的 测试(将打开一个测试窗口)。

  3. 如果需要,编辑 webhook 参数值。

  4. 单击 测试

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

4 Webhook - 图2

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

4 Webhook - 图3

如果 webhook 测试成功:

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

如果 webhook 测试失败:

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

用户媒介

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

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

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

配置告警动作时,请在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复选框,输入自定义消息内容 ,否则通知不会被发送出去。