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 repository下载它。
将文件Import到您的Zabbix安装中。webhook将出现在媒体类型列表中。
根据Readme.md文件中的说明配置webhook（您可以通过点击webhook名称上方的链接快速访问Readme.md）。

从零开始创建自定义webhook：

导航至Alerts → Media types。
点击Create media type。

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

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

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

参数	描述
Parameters	指定webhook变量为属性和值对。对于预配置的webhooks，参数列表会根据服务的不同而变化。检查webhook的Readme.md文件以了解参数描述。对于新的webhooks，会默认包含几个通用变量（URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}），您可以保留或删除它们。 webhook参数支持user macros，所有在问题通知中支持的macros，以及额外的{ALERT.SENDTO}，{ALERT.SUBJECT}，和{ALERT.MESSAGE}宏。如果您指定了一个HTTP proxy，该字段具有与在监控项配置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头和请求正文。脚本必须包含返回操作符，否则它将无效。它可以返回OK状态以及可选的标签和标签值列表（参见Process tags选项），或者返回一个错误 string。请注意，脚本仅在创建警报后执行。如果配置脚本返回并处理标签，这些标签在初始问题消息和恢复消息中的{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必须返回一个包含至少一个空标签object的JSON object：`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）并且不应在多个警报操作中使用for a single problem event。
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媒体类型：

在列表中找到相关的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的配置动作步骤与其他所有媒体类型相同，但有以下例外：

如果webhook使用webhook标签来存储工单，避免在单个问题事件的多个告警动作中使用相同的webhook。如果{EVENT.TAGS.<tag name>}存在并在webhook中更新，其结果值将是不确定的。为了避免这种情况，在webhook中使用新的标签名称来存储更新的值。这适用于Zabbix提供的Jira、Jira服务台、Mattermost、Opsgenie、OTRS、Redmine、ServiceNow、Slack、Zammad和Zendesk webhook，以及大多数使用包含事件菜单项选项的webhook。然而，需要注意的是，单个webhook可以在同一动作的不同操作或升级步骤中使用，以及在不同的动作中使用，这些动作不会因不同的条件而被同一问题事件触发。
在内部事件的动作中使用webhook时，确保勾选自定义消息复选框，并在动作操作配置中定义自定义消息。否则，不会发送通知。

Documentation

4 Webhook

概述

集成

配置

媒体类型测试

用户媒介

配置告警动作