[comment]: # ({56bf7160-56bf7160}) # 4 Webhook [comment]: # ({/56bf7160-56bf7160}) [comment]: # ({02b4d443-6584b266}) #### 概述 webhook 媒介类型可用于使用自定义 JavaScript 代码发起 HTTP 调用，从而与帮助台系统、聊天工具或即时通讯软件等外部软件进行直接集成。 您可以选择导入由 Zabbix 提供的集成，或从头开始创建自定义集成。 [comment]: # ({/02b4d443-6584b266}) [comment]: # ({d863deaf-27a06b1f}) #### 集成 以下集成可用，允许使用预定义的 webhook 媒介类型将 Zabbix 通知推送到： - [brevis.one](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/brevis.one/README.md) - [Discord](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/discord/README.md) - [Event-Driven Ansible](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/event_driven_ansible/README.md) - [Express.ms messenger](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/express.ms/README.md) - [GitHub](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/github/README.md) - [GLPI](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/glpi/README.md) - [IBM Maximo Service Request](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/maximo_service_request/README.md) - [iLert](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/ilert/README.md) - [iTop](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/itop/README.md) - [Jira](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/jira/README.md) - [Jira Service Management](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/jira_service_management/README.md) - [ManageEngine ServiceDesk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/manageengine_servicedesk/README.md) - [Mantis Bug Tracker](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/mantisbt/README.md) - [Mattermost](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/mattermost/README.md) - [MS Teams](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/msteams/README.md) - [MS Teams Workflows](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/msteams-workflow/README.md) - [LINE](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/line/README.md) - [Opsgenie](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/opsgenie/README.md) - [OTRS CE](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/otrs_ce/README.md) - [Pagerduty](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/pagerduty/README.md) - [Pushover](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/pushover/README.md) - [Redmine](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/redmine/README.md) - [Rocket.Chat](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/rocketchat/README.md) - [ServiceNow](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/servicenow/README.md) - [SIGNL4](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/signl4/README.md) - [Slack](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/slack/README.md) - [SolarWinds](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/solarwinds/README.md) - [SysAid](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/sysaid/README.md) - [Telegram](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/telegram/README.md) - [TOPdesk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/topdesk/README.md) - [VictorOps](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/victorops/README.md) - [Zammad](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/zammad/README.md) - [Zendesk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/zendesk/README.md) ::: notetip 除了此处列出的服务外，Zabbix 还可以与 **Spiceworks** 集成（无需 webhook）。 要将 Zabbix 通知转换为 Spiceworks 工单，请创建一个[电子邮件媒介类型](/manual/config/notifications/media/email)，并在指定 Zabbix 用户的配置文件设置中输入 Spiceworks 帮助台电子邮件地址（例如 help\@zabbix.on.spiceworks.com）。 ::: [comment]: # ({/d863deaf-27a06b1f}) [comment]: # ({2ff62d0e-d84f1038}) #### 配置 要开始使用 webhook 集成： 1. 在已下载的 Zabbix 版本的 `templates/media` 目录中找到所需的 .yaml 文件，或从 Zabbix [git repository](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media) 下载该文件。 2. 将该文件[导入](/manual/xml_export_import/media#importing)到您的 Zabbix 安装中。 webhook 将出现在媒介类型列表中。 3. 根据 *Readme.md* 文件中的说明配置 webhook（您可以点击上方的 webhook 名称以快速访问 *Readme.md*）。 要从头创建自定义 webhook： 1. 前往 *告警 > 媒介类型*。 2. 点击 *创建媒介类型*。 **媒介类型**选项卡包含此媒介类型特有的各种属性： ![](../../../../../assets/en/manual/config/notifications/media/media_webhook_express.png){width="600"} 所有必填输入字段都以红色星号标记。 以下参数是 webhook 媒介类型特有的： |参数|描述| |--|--------| |*参数*|将 webhook 变量指定为属性和值对。
对于预配置的 webhook，参数列表会因服务而异。请查看 webhook 的 *Readme.md* 文件了解参数说明。
对于新的 webhook，默认包含若干常见变量（URL:、HTTPProxy:、To:{ALERT.SENDTO}、Subject:{ALERT.SUBJECT}、Message:{ALERT.MESSAGE}），您可以保留或删除它们。

Webhook 参数支持[用户宏](/manual/appendix/macros/supported_by_location_user)、问题通知中支持的所有[宏](/manual/appendix/macros/supported_by_location)，以及额外支持的 {ALERT.SENDTO}、{ALERT.SUBJECT} 和 {ALERT.MESSAGE} 宏。

如果您指定了 HTTP proxy，该字段支持与监控项配置中的 [HTTP proxy](/manual/config/items/itemtypes/http#configuration) 字段相同的功能。proxy 字符串可带有前缀 `[scheme]://`，以指定所使用的 proxy 类型（例如 https、socks4、socks5；请参见[文档](https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html)）。| |*脚本*|在参数字段中点击或点击其旁边的铅笔图标时，会打开模态编辑器；请在其中输入 JavaScript 代码。该代码将执行 webhook 操作。
脚本是接受参数-值对的函数代码。应使用 JSON.parse() 方法将值转换为 JSON 对象，例如：`var params = JSON.parse(value);`。

代码可以访问所有参数，可执行 HTTP GET、POST、PUT 和 DELETE 请求，并支持 CONNECT、PATCH、HEAD、OPTIONS 和 TRACE 等附加方法，同时可控制 HTTP 标头和请求体。
脚本必须包含 return 运算符，否则将无效。它可以返回 OK 状态以及可选的标签和值列表（请参见 *处理标签* 选项），或者返回错误字符串。

恢复事件（无论是自动生成还是手动关闭产生）由服务器创建，并包含已解决的事件标签（包括从模板、主机和触发器继承的标签）。Webhook 脚本会在告警创建后执行；因此，webhook 脚本返回的标签仅会在初始告警创建之后添加，不会出现在初始问题消息或即时恢复消息的 [{EVENT.TAGS}](/manual/appendix/macros/supported_by_location#eventtags) 和 [`{EVENT.RECOVERY.TAGS}`](/manual/appendix/macros/supported_by_location#eventrectags) 宏中。
*注意*：建议使用局部变量（例如 `var local = 1`）而不是全局变量（例如 `global = 1`），以确保每个脚本都基于自己的数据运行，并避免并发调用之间发生冲突（请参见[已知问题](/manual/installation/known_issues#preprocessing--global-variables-are-unsafe)）。

另请参见：[Webhook 开发指南](https://www.zabbix.com/documentation/guidelines/en/webhooks)、[Webhook 脚本示例](/manual/config/notifications/media/webhook/webhook_examples)、[附加 JavaScript 对象](/manual/config/items/preprocessing/javascript/javascript_objects)。
| |*超时*|JavaScript 执行超时（1-60s，默认 30s）。
支持时间后缀，例如 30s、1m。| |*处理标签*|勾选此复选框以将返回的 JSON 属性值作为标签处理。这些标签会添加到任何现有的问题标签中。
请注意，使用 [webhook tags](https://www.zabbix.com/documentation/guidelines/en/webhooks#webhook-tags) 时，webhook 必须返回一个至少包含空 tags 对象的 JSON 对象：`var result = {tags: {}};`
可返回的标签示例：*jira-id:prod-1234*、*responsible:John Smith*、*processed:*| |*包含事件菜单项*|勾选此复选框，以在[事件菜单](/manual/web_interface/menu/event_menu)中包含一个指向已创建外部工单的链接项。
对于每个已启用且勾选了此复选框的 webhook，都会包含一个菜单项。请注意，如果 *菜单项名称* 和 *菜单项 URL* 参数中包含任何 [{EVENT.TAGS.}](/manual/appendix/macros/supported_by_location#events) 宏，则只有在这些宏可被解析时才会包含该菜单项（即事件已定义这些标签）。
如果勾选此项，则该 webhook 不应用于向不同用户发送通知（建议改为创建[专用用户](/manual/config/notifications/media/webhook#user-media)），也不应用于单个问题事件的多个告警动作中（请参见[针对单个问题事件](/manual/config/notifications/media/webhook#configuring-alert-actions)）。| |*菜单项名称*|指定菜单项名称。
支持 [{EVENT.TAGS.}](/manual/appendix/macros/supported_by_location#events) 宏。
仅当勾选 *包含事件菜单项* 时，此字段才是必填项。| |*菜单项 URL*|指定菜单项的底层 URL。
支持 [{EVENT.TAGS.}](/manual/appendix/macros/supported_by_location#events) 宏。
仅当勾选 *包含事件菜单项* 时，此字段才是必填项。| 有关如何配置默认消息和告警处理选项的详细信息，请参见[通用媒介类型参数](/manual/config/notifications/media#common-parameters)。 ::: notewarning 即使 webhook 不使用默认消息，仍必须为该 webhook 使用的操作类型定义消息模板。 ::: [comment]: # ({/2ff62d0e-d84f1038}) [comment]: # ({f9688d90-e5e73ea8}) #### 测试 要测试已配置的 webhook 媒介类型： 1. 在媒介类型[列表](/manual/config/notifications/media#overview)中找到相应的 webhook。 2. 单击列表最后一列中的 *Test*（将打开一个测试窗口）。 3. 根据需要编辑 webhook 参数值。 将宏替换为示例值；否则宏将无法解析，测试将失败。 4. 单击 *Test*。 在测试窗口中替换或删除值只会影响测试过程，实际的 webhook 属性值将保持不变。 ![](../../../../../assets/en/manual/config/webhook_test1.png){width="600"} 要在不离开测试窗口的情况下查看媒介类型测试日志条目，请单击 *Open log*（将打开一个新的弹出窗口）。 ![](../../../../../assets/en/manual/config/mediatype_test2.png){width="600"} [comment]: # ({/f9688d90-e5e73ea8}) [comment]: # ({817ae9ce-b2974109}) **如果 webhook 测试成功：** - 将显示 *“Media type test successful.”* 消息。 - 服务器响应将显示在灰色的 *Response* 字段中。 - *Response* 字段下方会标明响应类型（JSON 或 String）。 [comment]: # ({/817ae9ce-b2974109}) [comment]: # ({d11e9918-abfbc807}) **如果 webhook 测试失败：** - 将显示 *“Media type test failed.”* 消息，后跟其他失败详情。 [comment]: # ({/d11e9918-abfbc807}) [comment]: # ({22965c08-6eeec89a}) #### 用户介质 配置介质类型后，前往 *用户 > 用户* 部分，将 webhook 介质分配给现有用户，或创建一个新用户来代表该 webhook。 为现有用户设置用户介质的步骤对于所有介质类型都是通用的，详见[介质类型](/manual/config/notifications/media#user-media)页面。 如果 webhook 使用标签来存储工单\\消息 ID，请避免将同一个 webhook 作为介质分配给不同用户，因为这样做可能会导致 webhook 错误（适用于大多数使用 *包含事件菜单项* 选项的 webhook）。 在这种情况下，最佳实践是创建一个专用用户来代表该 webhook： 1. 配置 webhook 介质类型后，前往 *用户 > 用户* 部分，创建一个专用的 Zabbix 用户来代表该 webhook——例如，对于 Slack webhook，可使用用户名 *Slack*。 除介质外，所有设置都可以保留默认值，因为该用户不会登录 Zabbix。 2. 在用户资料中，前往 *介质* 选项卡，并[添加一个 webhook](/manual/config/notifications/media#user-media)，填写所需的联系信息。 如果 webhook 不使用 *发送到* 字段，请输入任意受支持字符的组合，以绕过验证要求。 3. 为该用户授予其需要发送告警的所有主机的至少只读[权限](/manual/config/users_and_usergroups/permissions#permissions-to-host-groups)。 配置告警动作时，在操作详情的 *发送到用户* 字段中添加该用户——这将告知 Zabbix 对此动作的通知使用该 webhook。 [comment]: # ({/22965c08-6eeec89a}) [comment]: # ({1b5d3274-ac89791d}) #### 配置告警动作 动作决定了应通过 webhook 发送哪些通知。 涉及 webhook 的[配置动作](/manual/config/notifications/action)步骤与所有其他媒介类型相同，但以下情况除外： - 如果 webhook 使用 [webhook 标签](https://www.zabbix.com/documentation/guidelines/en/webhooks#webhook-tags) 来存储工单\\消息 ID 并处理更新\\解决操作，请避免在单个问题事件中于多个告警动作中使用同一个 webhook。 如果存在 {EVENT.TAGS.} 且该值在 webhook 中被更新，则其结果值将是未定义的。 为避免这种情况，请在 webhook 中使用新的标签名称来存储更新后的值。 这适用于 Zabbix 提供的 Jira、Jira Service Desk、Mattermost、Opsgenie、OTRS、Redmine、ServiceNow、Slack、Zammad 和 Zendesk webhook，以及大多数使用 *Include event menu entry* 选项的 webhook。 但请注意，单个 webhook 可以在同一动作的多个操作或升级步骤中使用，也可以在不同动作中使用，只要这些动作不会因不同的[条件](/manual/config/notifications/action/conditions)而被同一个问题事件触发。 - 在针对[内部事件](/manual/config/events/sources#internal-events)的动作中使用 webhook 时，请确保勾选 *Custom message* 复选框，并在动作操作配置中定义自定义消息。 否则，将不会发送通知。 [comment]: # ({/1b5d3274-ac89791d})