• 指标监控
• 可观测性
• 告警
• 运维

本指南基于 Zabbix 官方仓库中的 MS Teams Workflow 媒体类型模板，系统讲解如何利用 Zabbix 的Webhook 媒体类型机制，将告警事件推送到 Microsoft Teams 频道。文章覆盖 Teams 侧 Workflow 的完整创建流程、Zabbix 侧全局宏 / 媒体类型 / 用户 / 动作的配置步骤、14 个 webhook 参数的作用与取值，并深入剖析 media_msteams_workflow.yaml 中 JavaScript 脚本的执行逻辑，帮助读者快速落地一套可用的 Teams 告警通道。

概述：Zabbix 与 MS Teams Workflow 的集成原理

Zabbix 的 Webhook 媒体类型本质上是一个内嵌的 JavaScript 执行引擎：当告警动作被触发时，Zabbix Server 的 escalator 模块取出媒体类型中配置的脚本与参数（见 src/zabbix_server/escalator/escalator.c 中对ZBX_SCRIPT_TYPE_WEBHOOK的处理），由 alerter 进程通过嵌入式脚本引擎执行该脚本（见 src/libs/zbxalerter/alerter.c 中的alerter_process_webhook），脚本内部再向目标 Webhook URL 发起 HTTP 请求。

本集成正是基于这一机制，让 Zabbix 通过 Teams 官方提供的Workflow（工作流）功能接收 Webhook 请求并在指定频道发布 Adaptive Card 卡片。其完整链路为：

Zabbix 事件 → 动作触发 → Webhook 脚本（JS）→ 构造 Adaptive Card JSON → HTTP POST → Teams Workflow → 频道发布卡片

适用前提：本集成仅在 Office 365 环境下的Teams中受支持，Teams 免费版不支持 MS Teams Workflow 功能。Zabbix 版本要求为8.0 及以上。

一、在 MS Teams 中创建 Workflow（Service 侧配置）

1. 进入 Workflows 应用

打开 Teams 客户端，在左侧垂直热栏中找到...（更多应用）入口，在弹出面板中搜索并点击Workflows应用：

2. 新建流程并选择模板

• 点击右上角的+ New flow按钮开始创建新流程（此时主页通常为空状态）。
• 在创建页面顶部的搜索栏输入关键词channel，从搜索结果中选择模板"Post a channel when a webhook request is received"（收到 Webhook 请求时向频道发布消息）。

3. 命名流程并选择发布账户

• 在Flow name输入框中填写流程名称（官方示例为Zabbix webhook）。
• 在Sign in菜单中选择合适的用户——该用户将用于创建频道帖子（即后续告警卡片的实际发布者）。
• 点击Next继续。

4. 绑定目标团队与频道

选择接收 Zabbix 事件的目标Microsoft Teams 团队（team）和频道（channel），点击Create Flow完成创建。

5. 保存 Workflow 端点 URL

创建成功后页面会提示Workflow added successfully。务必复制并保存弹出的 workflow endpoint URL——它将作为后续 Zabbix 媒体类型中teams_endpoint（即{ALERT.SENDTO}）的值，是连接两端的核心凭证。

6. 验证流程创建结果

关闭当前窗口，点击工作流菜单左上角的首页按钮，即可在流程列表中看到名为Zabbix webhook的新流程：

点击该流程可查看详情信息（归属者、状态、类型、关联 Teams 连接等）：

提示：移除卡片底部署名若希望去除卡片底部 "USERNAME used a Workflow to send this card. Get template" 的署名消息，需要在完成上述第 9 步（查看流程详情）后，点击Save as按钮将流程另存为副本，并使用新副本的端点 URL（而非第 7 步保存的原始 URL）配置 Zabbix。

二、Zabbix Webhook 参数详解

导入媒体类型后，可在 Zabbix 中通过 webhook 参数对其进行配置。参数分为可配置参数与内部参数两类。

可配置参数

可配置参数面向实际环境与个人偏好调整：

内部参数

内部参数由预定义宏提供，不应修改：

HTTP 代理支持：每个 webhook 均支持 HTTP 代理。如需使用，请在媒体类型中新增一个名为http_proxy的参数，并将其值设为代理 URL。该参数在脚本中通过this.request.setProxy(this.httpProxy)生效。

三、Zabbix 侧配置步骤

1. 设置全局宏{$ZABBIX.URL}

在 Zabbix Web 前端中，进入Administration（管理）→Macros（宏），配置全局宏{$ZABBIX.URL}为 Zabbix 前端的访问地址。

• 协议必填，端口可选。正确示例：
  • http://zabbix.com
  • https://zabbix.lan/
  • http://server.zabbix.lan/
  • http://localhost
  • http://127.0.0.1:8080
• 错误示例：
  • zabbix.com（缺少协议）
  • http://zabbix/（无法解析的主机名）

2. 导入媒体类型

进入Alerts（告警）→Media types（媒体类型），导入仓库提供的 media_msteams_workflow.yaml 文件。导入后媒体类型默认处于DISABLED（禁用）状态，需手动启用。

3. 创建用户并添加媒体

• 进入Users（用户）→Users（用户），点击右上角Create user（创建用户），在User（用户）选项卡中填写所有必填字段（红色星号标记）。
• 在Media（媒体）选项卡中，添加媒体类型并从下拉列表选择MS Teams Workflow；在Send to字段中填入第 7 步创建的 incoming webhook URL。
• 在Permissions（权限）选项卡中为用户选择合适角色，确保该用户对需要发送 Teams 告警的所有主机具有访问权限，否则无法收到对应主机的通知。

4. 开始接收告警

完成上述配置并启用媒体类型后，即可开始接收告警。

四、消息模板与 Markdown 支持

MS Teams Workflow 的 webhook 支持Adaptive Cards 的 Markdown 语法。如需使用，进入Alerts→Media types，找到MS Teams Workflow媒体类型，点击后在Message templates（消息模板）选项卡中选择目标消息模板，并使用 Markdown 语法编辑。

媒体类型自带的message_templates覆盖了触发器、发现、自动注册、内部事件、服务事件五类事件源。以触发器问题为例，默认模板为：

Problem started at {EVENT.TIME} on {EVENT.DATE} Problem name: {EVENT.NAME} Host: {HOST.NAME} Severity: {EVENT.SEVERITY} Operational data: {EVENT.OPDATA} Original problem ID: {EVENT.ID} {TRIGGER.URL}

五、源码级解析：Webhook 脚本如何工作

导入的 YAML 文件中内嵌了一段 JavaScript 脚本（media_msteams_workflow.yaml 的script字段），理解其执行流程有助于排查告警发送问题。

1. TLS 校验逻辑（CTlsConfig）

脚本将tls_verify参数归一化后映射为底层HttpRequest的 SSL 选项：

this.options = { SSLVerifyPeer: (raw_value === 'peer' || raw_value === 'full'), SSLVerifyHost: (raw_value === 'full') }; this.enabled = (raw_value !== 'none');

即：none完全关闭校验；peer校验证书链与有效期但不校验主机名；full同时校验证书与主机名。此外，checkURL会在启用校验时强制要求 URL 使用https://协议，否则抛出异常——这也解释了为什么 Teams 的 webhook 端点必须使用 HTTPS。

2. 参数校验（CParamValidator）

脚本内置了完整的参数校验器，onCheckParams阶段会对alert_subject、alert_message、zabbix_url、teams_endpoint进行字符串与 URL 格式校验，并对触发器事件校验event_id、trigger_id为整数。参数异常时，脚本会抛出Incorrect ... parameter之类的错误并记录到 Zabbix 日志。

3. 事件路由（handleEvent）

脚本依据event_source将事件路由到对应处理函数：

const types = { '0': 'Trigger', '1': 'Discovery', '2': 'Autoreg', '3': 'Internal', '4': 'Service' };

• 事件源为 0/3/4 时，根据event_update_status与event_value判定为Update/Problem/Resolve事件；
• 事件源为 1/2 时走无事件处理分支（Discovery / Autoreg）。

4. 卡片构造与颜色语义（onProblem / onResolve / onUpdate）

脚本构造的是application/vnd.microsoft.card.adaptive类型的 Adaptive Card（schema 版本 1.4），卡片主体依次为：加粗的alert_subject标题块、按行拆分的alert_message文本块，以及一个指向 Zabbix 事件详情页的Action.OpenUrl按钮（URL 由CWebhookHelper.createProblemURL基于zabbix_url与事件 ID 生成）。

不同事件类型使用不同的容器样式颜色，形成直观的视觉语义：

5. HTTP 发送与结果判定

发送采用POST请求，目标为teams_endpoint。脚本通过request.getStatus()检查 HTTP 状态码，非 2xx 响应视为发送失败，抛出包含状态码与响应正文的错误；2xx 响应则返回OK。

6. 告警调试

在alerter_process_webhook的实现（src/libs/zbxalerter/alerter.c）中可以看到，webhook 脚本由 Zabbix 内嵌脚本引擎执行，且支持以 debug 模式返回脚本调试信息——当告警发送失败时，可在告警详情中查看脚本输出与错误信息，辅助定位参数错误或网络问题。

六、常见问题排查思路

• 告警发送失败，日志出现Webhook processing failed：多为参数校验未通过，检查event_source、event_value、event_update_status等内部参数是否被误改，以及zabbix_url、teams_endpoint是否符合 URL 格式要求。
• TLS 校验相关错误：确认 Teams 端点使用https://协议；如网络环境确实需要跳过校验，可将tls_verify设为none（生产环境不推荐）。
• 收到HTTP code: xxx错误：检查 workflow 端点 URL 是否完整、是否已更换为Save as副本后的新 URL，以及发送账户对目标频道是否有发布权限。
• 未收到告警但媒体测试正常：检查动作（Action）配置中是否启用了 MS Teams Workflow 媒体、用户媒体中的Send to是否填入了正确的端点 URL，以及用户是否拥有目标主机的访问权限。
• 需要走代理：在媒体类型中新增名为http_proxy的参数并填入代理地址即可，脚本会通过setProxy使所有请求经由代理发送。

相关资源

• 集成文档：templates/media/msteams-workflow/README.md
• 媒体类型定义：templates/media/msteams-workflow/media_msteams_workflow.yaml
• Webhook 执行链路源码：src/libs/zbxalerter/alerter.c、src/zabbix_server/escalator/escalator.c

如在部署中遇到问题，可在 Zabbix 官方支持渠道（support.zabbix.com）提交 issue，或在 Zabbix 论坛的 Suggestions and Feedback 板块寻求帮助。

• 指标监控
• 可观测性
• 告警
• 运维