4 Webhook

概述

Webhook媒介类型对于使用自定义JavaScript代码进行HTTP调用非常有用，可方便地与外部软件（如帮助台系统、聊天工具或消息传递服务）集成。您可以选择使用Zabbix提供的import集成，或者从头开始创建自定义的create集成。

集成

以下集成功能可用，允许使用预定义的 webhook 媒介类型将 Zabbix 通知推送到：

除了此处列出的服务外，Zabbix 还可以与 Spiceworks 集成（不需要 webhook）。要将 Zabbix 通知转换为 Spiceworks 工单，请create一个email media type，并在指定 Zabbix 用户的媒介file设置中输入 Spiceworks 帮助台电子邮件地址（例如 [email protected]）。

配置

要开始使用Webhook集成：

在templates/media目录中定位所需的.xml file 已下载的Zabbix version 或从Zabbix git repository下载。
导入将 file 转换为您的Zabbix安装。该webhook将出现在列表中媒体类型。
根据Readme.md文件中的说明配置webhook file（您可点击上方任意Webhook名称快速访问 自述文件.md)。

从头开始create自定义webhook：

前往告警 → 媒介类型。
点击创建媒介类型。

媒体类型选项卡包含针对此类型的各种属性媒体类型：

所有必填字段均以红色星号标记。

以下参数专属于webhook媒体类型：

参数	描述
Parameters	以属性-值对的形式指定Webhook变量。对于预配置的Webhook，参数列表因服务而异，具体参数说明请查阅Webhook的Readme.md file文件。新建Webhook时默认包含几个通用变量（URL:<空>、HTTPProxy:<空>、收件人:{ALERT.SENDTO}、主题:{ALERT.SUBJECT}、消息:{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），以确保每个脚本操作自己的数据，并避免同时调用之间的冲突（参见跨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、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媒介类型：

在媒介类型列表概述中找到相关的Webhook。
点击列表最后一列的测试（将会打开一个测试窗口）。
根据需要编辑Webhook参数值。将宏替换为示例值；否则宏将无法解析，测试将会失败。
点击测试。

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

如需在不离开测试窗口的情况下查看媒介类型测试日志条目，请点击打开日志（将会打开一个新的弹出窗口）。

如果 webhook 测试成功：

显示 "Media type test successful." 消息。
服务器响应显示在灰色的 Response 字段中。
响应该字段下方会显示响应类型（JSON 或 string）。

如果 webhook 测试失败：

显示 "Media type test failed." 错误消息，随后显示更详细的失败信息。

用户媒介

一旦媒体类型配置完成，请转到 用户 → 用户 界面，将该webhook媒体类型分配给一个现有用户，或者使用create创建一个新用户来代表该webhook。为现有用户配置用户媒体的步骤对于所有媒体类型来说是通用的，具体描述请参见用户媒介页面。

如果某个webhook使用标签存储工单/消息ID，请避免将相同的webhook作为媒体分配给不同的用户，因为这可能会导致webhook错误（适用于大多数使用包含事件菜单项选项的webhook）。在这种情况下，最佳实践是使用create创建一个专用用户来代表该webhook：

配置完webhook媒体类型后，进入 用户 → 用户 界面，使用create创建一个专用的Zabbix用户来代表该webhook —— 例如，对于Slack webhook，可以设置用户名为 Slack。除媒体信息外，其他所有设置均可保留默认值，因为该用户不会登录Zabbix系统。
在用户配置界面中，进入媒介标签页，并使用用户媒介填写所需的联系方式。如果该webhook不使用发送至字段，请输入任意支持的字符组合以绕过验证要求。
至少授予该用户对所有需要发送告警的主机的读取主机组权限权限。

在配置告警动作时，在操作详情的 发送给用户 字段中添加该用户 —— 这将告诉Zabbix在该动作的告警通知中使用该webhook。

配置告警动作

动作决定应通过 webhook 发送哪些通知。
涉及 webhook 的 configuring actions 步骤与所有其他媒介类型的步骤相同，但有以下例外：

如果 webhook 使用 webhook tags 来存储工单\消息 ID 并处理更新\解决操作，请避免在单个问题事件的多个告警动作中使用相同的 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 处理内部事件时，请务必勾选 自定义消息 复选框，并在动作操作配置中定义自定义消息。
否则，通知将不会被发送。

Documentation

4 Webhook

概述

集成

配置

媒介类型测试

用户媒介

配置告警动作