Metabase Webhooks 配置指南将告警结果投递到任意 HTTP 端点【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabaseMetabase 的 Webhooks 功能允许管理员为告警Alerts配置自定义 HTTP 回调端点把问题Question的查询结果以 JSON 形式推送到你自己的应用、第三方服务或任意目标 URL。本文将从 Webhook 的创建配置、四种认证方式、JSON Payload 结构与底层源码实现四个层面展开帮助你完整掌握在 Metabase 中接入 Webhooks 并基于告警结果构建自动化通知管线的实战方法。Webhook 适用场景与权限要求在 Metabase 中Webhook 是告警投递通道的一种与 Email、Slack 并列三者分别对应源码中的:channel/http、:channel/email、:channel/slack见 channel.clj。它的核心能力是为某个 Question 设置告警后Metabase 会把该查询的告警结果发送到你指定的 URL 端点。使用 Webhook 前需要明确两点限制仅管理员和拥有设置访问权限Settings access的用户可以创建 Webhook 并设置发送到 Webhook的告警。设置访问权限的说明见应用权限文档。当前 Webhook 仅支持告警Alerts作为触发来源尚不能把 Webhook 选为仪表盘订阅Dashboard subscriptions的接收者。一个典型的使用场景是团队在 Metabase 中维护一份关键业务指标如每日销售额的 Question当指标触发设定条件时Metabase 将结果 JSON 推送到公司内部的消息网关或数据管道实现指标异常自动通知、数据自动归档等联动能力。创建 WebhookAdmin 控制台操作步骤入口路径Admin管理后台 Settings设置 Webhooks完整创建流程如下点击界面右上角的网格grid图标选择Admin进入管理控制台在 Admin 控制台中依次进入Settings Webhooks在Webhooks for alerts用于告警的 Webhook区域点击Add a webhook添加 Webhook在表单中填写以下字段字段说明Webhook URL希望 Metabase 发送告警结果的地址必须是一个合法 URL必须是http://或https://协议Name名称为 Webhook 命名方便用户在设置 Question 告警时正确选用Description描述说明该 Hook 的用途帮助团队成员理解使用场景Authentication method认证方式四种可选None、Basic、Bearer、API key详见下文创建完成后管理员需要先在**告警Alerts**页面中把某个 Question 的告警接收者设置为该 WebhookMetabase 才会在触发条件满足时向该 URL 发送请求。告警的完整配置流程参见告警文档。四种认证方式详解Webhook 的认证方式决定了 Metabase 发送 HTTP 请求时如何携带访问凭证具体选项如下None无认证Metabase 直接发送请求不附加任何认证信息适用于内网可信端点或无需鉴权的接收服务Basic基本认证设置用户名和密码Metabase 会在请求头中附加 HTTP Basic Auth 凭证Authorization: Basic ...BearerBearer Token携带一个秘钥令牌secret token对应 RFC 6750 定义的 Bearer Token 认证方式Metabase 会在请求头中附加Authorization: Bearer tokenAPI keyAPI 密钥支持两种放置位置——Header请求头或Query param查询参数。两种方式都需要提供键key和值value即 API key 本身。例如选择 Header 方式时可以设置X-Api-Key: your-key选择 Query param 方式时Metabase 会在 URL 上附加?your-keyvalue之类的参数。从源码看这四种认证方式在后端被归并为三类请求注入位置且与前端表单类型一一对应见 http.clj 中的HTTPDetailsschema前端fe-form-type实际注入位置auth-method行为nonenone不注入任何认证信息basic/bearerheader将auth-info合并进请求头api-keyHeader 方式header将键值对合并进请求头api-keyQuery param 方式query-param将键值对合并进查询参数在发送请求时后端channel/send!会根据auth-method的值决定把auth-info合并到:headers还是:query-params见 http.clj默认使用POST方法也支持在通道配置中指定get或put见 http.clj。Webhook Payload告警结果的 JSON 结构当告警触发时Metabase 会向 Webhook URL 发送一个 JSON 请求体Content-Type 为application/json其中包含 Question 的元数据与查询结果。Payload 顶层包含type、alert_id、alert_creator_id、alert_creator_name、data和sent_at六个字段type固定为alert标识该通知为告警类型alert_id告警的 ID在测试告警test alerts场景下为nullalert_creator_id创建该告警的用户 IDalert_creator_name创建该告警的用户名称data核心数据对象包含 Question 信息、可视化图表与表格数据sent_at发送时间格式为 ISO 8601 带时区时间戳例如2024-09-30T20:16:15.76582Z。其中data对象包含以下字段type固定为questionquestion_id告警所关联 Question 的 IDquestion_nameQuestion 的名称question_urlQuestion 的完整 URL例如https://example.com/question/108visualization告警所附加的图表可视化以 base64 编码的 PNG 图片数据data URI形式提供raw_data与表格视图一致的原始查询结果包含cols列名数组与rows二维数据数组。raw_data中的rows每行元素与cols中的列名按顺序一一对应。以下是一个告警触发后的完整 Payload 示例PNG 编码部分已截断{ type: alert, alert_id: null, alert_creator_id: 2666, alert_creator_name: Roberto Bolaño, data: { type: question, question_id: 108, question_name: Sales, question_url: https://example.com/question/108, visualization: data:image/png;base64,...LONG_ENCODED_PNG_HERE..., raw_data: { cols: [ CREATED_AT, count ], rows: [ [ 2023-09-01T00:00:00Z, 346 ], [ 2023-10-01T00:00:00Z, 354 ], [ 2023-11-01T00:00:00Z, 394 ], [ 2023-12-01T00:00:00Z, 418 ], [ 2024-01-01T00:00:00Z, 457 ], [ 2024-02-01T00:00:00Z, 404 ], [ 2024-03-01T00:00:00Z, 445 ], [ 2024-04-01T00:00:00Z, 439 ], [ 2024-05-01T00:00:00Z, 520 ], [ 2024-06-01T00:00:00Z, 455 ], [ 2024-07-01T00:00:00Z, 523 ], [ 2024-08-01T00:00:00Z, 501 ] ] } }, sent_at: 2024-09-30T20:16:15.76582Z }源码级解析Webhook 的发送链路与底层实现通道模型HTTP 通道即 Webhook在 Metabase 的通道Channel抽象中Webhook 本质上是:channel/http类型的通道。通道配置的details字段由HTTPDetailsschema 约束见 http.clj包含url、auth-method取值none/header/query-param/request-body、auth-info、fe-form-type取值api-key/bearer/basic/none以及请求方法method取值get/post/put。通道的创建、更新通过 channel.clj 中的 REST API 完成/api/channel端点会按type分发到对应的detailsschema 进行校验。发送与渲染render-notification → send!Webhook 的告警投递由两个核心方法协作完成channel/render-notification [:channel/http :notification/card]负责把告警事件渲染为 HTTP 请求体。它从 payload 中取出 Questioncard、告警notification_card与创建者creator信息构造出与前文 Payload 示例完全一致的 JSON 结构其中visualization通过render-pulse-card-to-base64将图表渲染为 base64 编码的 PNG渲染宽度上限为 1200 像素见 http.clj 与 render/core.cljraw_data由qp-result-raw-data从查询处理器QP结果中提取cols列名列表与rows数据行见 http.cljsent_at使用带时区的当前时间t/offset-date-time生成见 http.clj。channel/send! :channel/http负责真正发出 HTTP 请求。发送前会执行 URL 校验check-url!与网络策略检查然后将认证信息合并到请求头或查询参数最后通过clj-http库发送请求见 http.clj。网络安全策略外部主机白名单控制为避免 Webhook 端点被滥用为内网探测工具SSRF 风险Metabase 通过设置项http-channel-allowed-networks控制允许访问的主机范围见 settings.clj支持三个取值external-only默认仅允许外部主机禁止访问内网与 localhostallow-private允许外部主机与私网地址但仍禁止 localhostallow-all不做限制包括 localhost。该设置项是内部设置visibility :internal可通过环境变量MB_HTTP_CHANNEL_ALLOWED_NETWORKS配置。在channel/send!中Metabase 会基于该策略创建 DNS 解析器network-policy-dns-resolver并对目标 URL 做宿主校验明确拒绝提供内部托管元数据如云厂商 metadata 服务的主机同时移除请求中携带的 DNS 解析器防止渲染出的请求自行控制 DNS 解析见 http.clj 与 http.clj。测试用例 http_test.clj 中的send!-rejects-any-local-ula-cgnat-test与send!-attaches-dns-resolver-test即为这些安全机制的验证。重试机制失败的告警投递自动重试Webhook 投递失败时Metabase 的通道重试机制会按指数退避策略自动重试相关设置见 settings.clj设置项默认值说明retry-max-retries6开发模式为 0最大重试次数retry-initial-interval500 ms首次重试的初始延迟retry-multiplier2.0每次重试的延迟倍数retry-jitter-factor0.1抖动因子避免重试请求集中retry-max-interval-millis30000 ms最大重试间隔上限以上设置均可通过对应的MB_RETRY_*环境变量在部署时调整使 Webhook 投递在面对瞬时故障时更具韧性。连接测试can-connect?在管理界面添加 Webhook 后Metabase 会通过channel/can-connect? :channel/http对目标端点进行一次连通性验证。该函数首先校验details是否符合HTTPDetailsschema然后实际发送一次请求若收到异常 HTTP 状态码会抛出包含状态码与响应体的Failed to connect to channel错误见 http.clj。对应的连通性测试覆盖了无认证、Header 认证、Query param 认证、请求体认证等全部场景见 http_test.clj 中的can-connect-*系列用例。实践建议与排查要点先在测试环境验证端点创建 Webhook 后使用发送测试告警功能验证 Payload 结构与认证配置是否正确测试告警的alert_id为null可作为识别测试请求的标志。优先选择安全的认证方式对于公网端点务必配置 Basic、Bearer 或 API key 认证同时注意http-channel-allowed-networks的默认值external-only如需接收内网地址的告警推送需显式放宽策略。合理设计接收端由于visualization为 base64 PNG 且raw_data可能较大接收端应支持大体积 JSON 请求体若图表包含大量列渲染宽度超过 1200 像素的部分会被截断。善用 Payload 中的元数据question_id与question_name可用于接收端对告警来源进行分类归档sent_at可用于记录投递延迟。延伸阅读告警Alerts完整配置指南仪表盘订阅Dashboard subscriptions应用权限与设置访问权限说明HTTP 通道实现源码http.clj通道相关设置项源码settings.clj通道 API 与 schema 校验源码channel.cljHTTP 通道测试用例http_test.clj【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考