Documentation
4 Webhook
概述
webhook 媒体类型对于使用自定义的JavaScript代码进行HTTP调用非常有用，它可以直接与外部软件（如 Helpdesk 系统、聊天工具或信使）进行集成。您可以选择使用 Zabbix 提供的集成方式或创建一个自定义集成方式。
集成
以下集成方式允许使用预定义的webhook媒介类型来推送Zabbix通知:
- brevis.one
- Discord
- Express.ms messenger
- Github issues
- iLert
- iTop
- Jira
- Jira Service Desk
- ManageEngine ServiceDesk
- Mattermost
- Microsoft Teams
- Opsgenie
- OTRS
- Pagerduty
- Pushover
- Redmine
- Rocket.Chat
- ServiceNow
- SIGNL4
- Slack
- SolarWinds
- SysAid
- Telegram
- TOPdesk
- VictorOps
- Zammad
- Zendesk
除了这里列出的服务外，Zabbix还可以集成 Spiceworks (无需webhook)。要把Zabbix通知转换成Spiceworks单据，需先创建一个电子邮件媒介类型 ，并在指定的Zabbix用户配置设置中输入Spiceworks helpdesk的邮件地址(例如 [email protected])。
配置
开始使用webhook集成:
- 在已下载的 Zabbix 的
templates/media目录中，找到所需的.xml文件；或者从Zabbix的 git仓库中下载 - 将文件导入 到 Zabbix 安装，Webhook 将出现在媒体类型列表中。
- 根据 Readme.md 文件中的说明来配置 webhook （也可以点击 webhook's 名称来快速访问 Readme.md ） 。
从零开始创建一个自定义的webhook:
- 进入管理 → 媒介类型
- 点击创建媒介类型
媒介类型选项卡包含了针对这种媒介类型的各种属性:
红色星号标记的为必填字段。
webhook媒介类型的具体参数如下:
| 参数 | 说明 |
|---|---|
| 参数 | webhook变量作为属性和值对。 对于预先配置的webhook，参数列表会随着服务的不同而变化。检查webhook的Readme.md 参数说明文件。 对于新的webhooks，默认情况下包含了几个常见的变量 (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}), 你可以保留或删除它们。 参数中支持问题通知中支持的所有宏 如果指定了HTTP Proxy，该字段支持与监控项配置HTTP proxy字段相同的功能。 Proxy字符串可以加上前缀 [scheme]:// 来指定使用哪种代理例如https, socks4, socks5; 请参见documentation). |
| 脚本 | 在点击参数字段(或旁边的查看/编辑按钮)时出现的块中输入JavaScript代码。这段代码将执行webhook操作。 脚本是接受参数-值对的一段功能代码，它的值应该使用JSON.parse() 方法转换为JSON对象，例如： var params = JSON.parse(value);.代码可以访问所有参数，它可以执行HTTP GET、POST、PUT和DELETE请求，并可控制HTTP头和请求正文。 脚本必须包含一个返回值，否则它将无效。它可以返回OK状态以及一个可选的标签列表，标签值(参见Process tags选项)，或一个错误的字符串。 注意，脚本只有在创建警报之后才会执行。如果脚本被配置为返回和处理标签 (参见处理标签 选项),这些标签将不会在初始问题消息和恢复消息中的 {EVENT.TAGS} 和 {EVENT.RECOVERY.TAGS} 宏中解析，因为脚本还没有时间运行。 另请参阅： Webhook开发指南, Webhook脚本样例, 额外的 JavaScript 对象. |
| 超时 | JavaScript执行超时 (1-60s, 默认为30s)。 支持时间后缀, 例如 30s, 1m。 |
| 处理标签 | 选中复选框标以将返回的JSON属性值作为标签处理。这些标签将被添加到Zabbix中已经存在的(如果有的话)问题事件标签中。 如果webhook使用了标签(Process tags复选框被选中),webhook应该返回一个至少带有一个空标签的JSON对象 var result = {tags: {}};.返回的标签示例: Jira ID: PROD-1234, Responsible: John Smith, Processed:<no value>, 等. |
| 包括事件菜单项 | 选中复选框以在事件菜单 中包含一个链接到创建的外部目标的条目。 若选中此项，webhook就不应该被用来向不同的用户发送通知 (考虑创建一个专有用户) 或者在几个告警动作中关联单个问题事件. |
| 菜单项名称 | 指定菜单入口名称。 支持{EVENT.TAGS.<tag name>}宏 只有当包括事件菜单项 被选中时，该字段才为必填项。 |
| 菜单项URL | 指定菜单入口的URL。 支持{EVENT.TAGS.<tag name>} 宏 只有当包括事件菜单项 被选中时，该字段才为必填项。 |
关于如何配置默认消息和告警处理选项的详细信息，请参见 通用媒介类型参数
即使webhook不使用默认消息，webhook使用的操作类型的消息模板也必须定义。
Media type testing
To test a configured webhook media type:
- Locate the relevant webhook in the list of media types.
- Click on Test in the last column of the list (a testing window will open).
- Edit the webhook parameter values, if needed.
- Click on Test.
By default, webhook tests are performed with parameters entered during configuration. However, it is possible to change attribute values for testing. Replacing or deleting values in the testing window affects the test procedure only, the actual webhook attribute values will remain unchanged.
To view media type test log entries without leaving the test window, click on Open log (a new popup window will open).
If the webhook test is successful:
- "Media type test successful." message is displayed
- Server response appears in the gray Response field
- Response type (JSON or String) is specified below the Response field
If the webhook test fails:
- "Media type test failed." message is displayed, followed by additional failure details.
用户媒介
媒介类型配置完成后， 前往 管理 → 用户 部分，为一个现有用户或创建一个新用户并指定其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的configuring actions 步骤与所有其他媒体类型相同，但有以下例外:
- 如果webhook使用标签来存储 ticket\message ID 以及后续的 update\resolve operations 操作, 这个webhook不应该用于单个问题事件的多个告警动作中。这适用于Zabbix提供的Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad和Zendesk webhooks以及大多数使用 Include event menu entry 选项的webhook。 如果操作或升级步骤属于同一个动作，允许在多个操作中使用webhook。在不同的动作中使用webhook也是可以的，由于不同的筛选器条件，动作不会应用到相同的问题事件中。
- 当在动作中使用webhook用于 internal events: 在动作操作配置中，选中 Custom message复选框，输入自定义消息内容 ，否则通知不会被发送出去。