4 Webhook

概述

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

集成

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

除此处列出的服务外，Zabbix还可与Spiceworks集成（无需webhook）。 要将Zabbix通知转换为Spiceworks工单，create一个email media type并在指定Zabbix用户的配置文件中输入Spiceworks帮助台邮箱地址（例如help\@zabbix.on.spiceworks.com）。

配置

开始使用Webhook集成:

  1. 在下载的Zabbix version的templates/media目录中找到所需的.yaml file，或从Zabbix git repository下载。
  2. 导入将file导入您的Zabbix安装。 Webhook将出现在媒介类型列表中。
  3. 根据Readme.md file中的说明配置Webhook（您可以点击上方的Webhook名称快速访问Readme.md）。

从头开始create自定义Webhook:

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

媒介类型标签页包含此媒介类型的各种特定属性:

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

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

参数 描述
Parameters 将Webhook变量指定为属性-值对。
对于预配置的Webhook，参数列表因服务而异。请查看Webhook的Readme.md file获取参数描述。
对于新的Webhook，默认包含几个常见变量(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，该字段支持与监控项配置配置字段相同的功能。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。

注意，脚本仅在告警创建后执行。如果脚本配置为返回和处理标签，这些标签不会在初始问题消息和恢复消息中的{EVENT.TAGS}和{EVENT.RECOVERY.TAGS}宏中get解析，因为脚本尚未有时间run。
注意：建议使用局部变量(如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都会包含一个条目。注意，如果菜单条目名称和菜单条目URL参数包含任何事件宏，则仅当这些宏可以解析时(即事件定义了这些标签)才会包含条目。
如果勾选，Webhook不应用于向不同用户发送通知(考虑创建用户媒介替代)，也不应在多个告警动作配置告警动作中使用。
Menu entry name 指定菜单条目名称。
支持事件宏。
仅当勾选包含事件菜单条目时，此字段为必填。
Menu entry URL 指定菜单条目的基础URL。
支持事件宏。
仅当勾选包含事件菜单条目时，此字段为必填。

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

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

测试

测试配置的webhook媒体类型：

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

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

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

如果webhook测试成功：

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

如果Webhook测试失败：

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

用户媒介

配置完媒介类型后，前往用户 > 用户板块，将webhook媒介分配给现有用户或create新用户来代表该webhook。 为现有用户设置用户媒介的步骤（适用于所有媒介类型）已在用户媒介页面描述。

若webhook使用标签存储工单/消息ID，请避免将同一webhook作为媒介分配给不同用户，否则可能导致webhook错误（适用于大多数使用包含事件菜单入口选项的webhook）。 此时最佳实践是create一个专用用户来代表该webhook：

  1. 配置完webhook媒介类型后，前往用户 > 用户板块并create一个专用的Zabbix用户代表webhook——例如用用户名Slack表示Slack webhook。 除媒介外的所有设置均可保留默认值，因该用户不会登录Zabbix。
  2. 在用户配置文件中，切换到媒介标签页并add a webhook填写必要的联系信息。 若webhook不使用发送至字段，可输入任意有效字符组合以满足验证要求。
  3. 授予该用户至少读取主机组权限权限到所有需要发送告警的主机。

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