4 Webhook

概述

Webhook媒介类型适用于通过自定义JavaScript代码发起HTTP调用,以便与外部系统(如帮助台系统、聊天工具或即时通讯软件)实现直接集成。您可以选择importZabbix提供的集成方案,或create从头开始构建自定义集成方案。

集成

以下集成方案可用,允许使用预定义的webhook媒体类型将Zabbix通知推送至:

除列出的服务外,Zabbix还可与Spiceworks集成(无需webhook)。要将Zabbix通知转换为Spiceworks工单,需create一个email media type并在指定Zabbix用户的配置文件中输入Spiceworks帮助台邮箱地址(例如[email protected])。

配置

开始使用Webhook集成:

  1. 在下载的Zabbix version的templates/media目录中找到所需的.xml file,或从Zabbix git repository下载

  2. 导入将file导入到您的Zabbix安装中。该Webhook将出现在媒介类型列表中。

  3. 根据Readme.md中的说明配置Webhook

    file (you may click on a webhook's name above to quickly access Readme.md).

要从头开始create自定义Webhook:

  • 前往管理 → 媒介类型
  • 点击创建媒介类型

媒介类型选项卡包含此媒介类型的各种特定属性:

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

以下参数是Webhook媒介类型特有的:

参数 描述
Parameters 将Webhook变量指定为属性-值对。
对于预配置的Webhook,参数列表因服务而异。请查看Webhook的Readme.md file获取参数描述。
对于新Webhook,默认包含几个常见变量(URL:<空>, HTTPProxy:<空>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}),可自由保留或删除。
所有macros在问题通知中支持的宏在参数中都受支持。
如果指定HTTP proxy,该字段支持与监控项配置配置字段相同的功能。proxy string可以前缀[scheme]://来指定使用哪种proxy(例如https, socks4, socks5; 参见documentation)。
Script 在点击参数字段(或其旁边的查看/编辑按钮)后出现的块中输入JavaScript代码。此代码将执行Webhook操作。
脚本是一个接受参数-值对的函数代码。应使用JSON.parse()方法将值转换为JSON objects,例如:var params = JSON.parse(value);

代码可以访问所有参数,可以执行HTTP GET、POST、PUT和DELETE请求,并控制HTTP头和请求体。
脚本必须包含return操作符,否则无效。它可以返回OK状态及可选的标签和标签值列表(参见处理标签选项)或错误string。

注意脚本仅在警报创建后执行。如果脚本配置为返回并处理标签,这些标签不会get在初始问题消息和恢复消息中的{EVENT.TAGS}和{EVENT.RECOVERY.TAGS}宏中解析,因为脚本尚未有时间run。
注意:建议使用局部变量而非全局变量,确保每个脚本操作自己的数据且同时调用间无冲突(参见跨webhook调用共享全局变量的使用场景)。

另见:Webhook development guidelines, Webhook script examples, Additional JavaScript objects
Timeout JavaScript执行超时(1-60秒,默认30秒)。
支持时间后缀,例如30s, 1m。
Process tags 勾选复选框以将返回的JSON属性值作为标签处理。这些标签会添加到任何现有问题标签中。
注意使用webhook tags时,Webhook必须返回包含至少空标签object的JSON object:var result = {tags: {}};
可返回的标签示例:Jira ID: PROD-1234, 负责人: John Smith, 已处理:<无值>
Include event menu entry 勾选复选框以在事件菜单中包含链接到创建的外部票据的条目。
每个启用且勾选此复选框的Webhook都会包含一个条目。注意如果菜单条目名称菜单条目URL参数包含任何{EVENT.TAGS.<tag name>}宏,仅当这些宏可解析时(即事件已定义这些标签)才会包含条目。
如果勾选,Webhook不应用于向不同用户发送通知(考虑创建用户媒介替代)且不应在多个告警动作配置告警动作中使用。
Menu entry name 指定菜单条目名称。
支持{EVENT.TAGS.<tag name>}宏。
仅当包含事件菜单条目勾选时此字段必填。
Menu entry URL 指定菜单条目的基础URL。
支持{EVENT.TAGS.<tag name>}宏。
仅当包含事件菜单条目勾选时此字段必填。

参见通用参数了解如何配置默认消息和告警处理选项的详细信息。

即使Webhook不使用默认消息,仍必须定义此Webhook使用的操作类型的消息模板。

用户媒介

配置媒体类型后,前往管理 → 用户部分,将webhook媒体分配给现有用户或create一个新用户来代表该webhook。为现有用户设置用户媒体的步骤(适用于所有媒体类型)已在用户媒介页面中描述。

如果webhook使用标签存储票据\消息ID,请避免将同一webhook作为媒体分配给不同用户,否则可能导致webhook错误(适用于大多数使用包含事件菜单项选项的webhook)。这种情况下,最佳实践是create一个专用用户来代表该webhook:

  1. 配置webhook媒体类型后,前往管理 → 用户部分并create一个专用的Zabbix用户来代表webhook - 例如,为Slack webhook创建用户名为Slack的用户。除媒体外,所有设置均可保留默认值,因为该用户不会登录Zabbix。

  2. 在用户配置文件中,转到媒体选项卡并用户媒介填写必要的联系信息。如果webhook不使用发送至字段,可输入任意支持的字符组合以绕过验证要求。

  3. 授予该用户至少读取权限

    permissions to all hosts for which it should send the alerts.

配置告警动作时,在操作详情的发送至用户字段中添加此用户 - 这将指示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时, 请确保勾选自定义消息复选框并在操作配置中定义自定义消息. 否则, 将不会发送通知.