Pulse 告警 Webhook 集成指南:服务模板、签名校验与投递契约
Pulse 告警 Webhook 集成指南:服务模板、签名校验与投递契约
Pulse 内置了面向 Discord、Slack、Teams、Telegram、PagerDuty、Pushover、Gotify、ntfy 等主流服务的 Webhook 模板,同时为自定义端点提供基于 Go 模板的通用 JSON 载荷定制能力。本文以 docs/WEBHOOKS.md 为主线,结合 internal/notifications/webhook_templates.go 与 internal/notifications/notifications.go 的源码实现,系统讲解如何配置告警投递、如何利用 HMAC 签名验签、如何理解"投递契约"中稳定的字段与语义,以及在 MSP 与多租户场景下的集成模型,帮助你构建可靠且可去重的工单/事件桥接。
一、快速上手:三条路径完成首个 Webhook
在 Pulse 的界面中,完成一个 Webhook 只需三步:
- 进入 告警(Alerts)→ 通知(Notifications)。
- 点击 添加 Webhook(Add Webhook)。
- 点击当前服务标签(默认为 Generic)打开服务选择器,选择目标服务类型并粘贴目标 URL。
添加完成后,可在配置项中继续设置自定义请求头、signingSecret 签名密钥、标签过滤与最低严重度等,详见下文各节。
从源码结构看,服务选择器对应的模板数据来自
GetWebhookTemplates(),该方法在 internal/notifications/webhook_templates.go 中返回一组WebhookTemplate,每个模板携带URLPattern、Method、Headers、PayloadTemplate与ResolvedPayloadTemplate(告警触发与恢复两套载荷模板),UI 层面的"选择服务即填充 URL 格式与请求头"正是基于这份清单。
二、内置服务模板与 URL 格式
下表汇总了各服务的内置模板与对应的 URL 格式(与源码中 URLPattern 一致):
| 服务 | URL 格式 |
|---|---|
| Discord | https://discord.com/api/webhooks/{id}/{token} |
| Slack | https://hooks.slack.com/services/... |
| Teams | https://{tenant}.webhook.office.com/webhookb2/{webhook_path} |
| Teams(Adaptive Card) | https://{tenant}.webhook.office.com/webhookb2/{webhook_path} |
| Telegram | https://api.telegram.org/bot{bot_token}/sendMessage?chat_id={chat_id} |
| PagerDuty | https://events.pagerduty.com/v2/enqueue |
| Pushover | https://api.pushover.net/1/messages.json |
| Gotify | https://gotify.example.com/message?token={token} |
| ntfy | https://ntfy.sh/{topic} |
| Generic | https://example.com/webhook |
除上述之外,模板清单中还包含 Mattermost(https://{your-mattermost-server}/hooks/{webhook_id}),同样提供触发与恢复两套 Markdown 表格载荷(见 webhook_templates.go)。各模板默认使用 POST 方法并携带 Content-Type 请求头(ntfy 使用 text/plain,PagerDuty 额外带有 Accept: application/vnd.pagerduty+json;version=2)。
各服务模板的载荷设计可以直接在 webhook_templates.go 中查看,例如 Discord 模板会按严重度切换 embed 颜色、按 diskRead/diskWrite 类型自动追加 "MB/s" 单位,并支持 {{.Mention}} 占位(Discord 的 @everyone、<@USER_ID> 或 <@&ROLE_ID>)。
三、自定义 JSON 模板(Generic)
对于通用 Webhook,Pulse 使用 Go 模板语法格式化 JSON 载荷。以 Generic 模板为例,其默认载荷结构在 webhook_templates.go 中定义,包含 event、alert(id、message_key、level、type、resource_type、resource_name、node、value、threshold、start_time、duration 等)以及可选的 tenant 对象。
3.1 可用变量(通用)
{{.ID}}、{{.Event}}、{{.MessageKey}}、{{.Level}}、{{.Type}}{{.ResourceName}}、{{.ResourceID}}、{{.ResourceType}}、{{.Node}}、{{.NodeDisplayName}}{{.Message}}、{{.Value}}、{{.Threshold}}、{{.Duration}}、{{.Timestamp}}{{.Instance}}(Pulse 公网地址,若已配置){{.TenantID}}、{{.TenantName}}(多租户组织与 MSP 客户端运行时的租户标识;普通单租户安装下为空){{.CustomFields.<name>}}(界面中用户自定义字段){{.Metadata}}(告警元数据 map){{.AlertCount}}、{{.Alerts}}(分组告警){{.Mention}}(平台特定的提及对象,若已配置)
3.2 便利字段
{{.ValueFormatted}}、{{.ThresholdFormatted}}{{.StartTime}}、{{.Acknowledged}}、{{.AckTime}}、{{.AckUser}}- 恢复相关字段还包括
{{.ResolvedAt}}、{{.NotRecovered}}(见各模板的ResolvedPayloadTemplate)
从源码看,prepareWebhookData() 在 notifications.go 中组装上述字段:Value/Threshold 会被四舍五入到 1 位小数以便载荷更干净;Instance 优先取 publicURL(并去除尾部斜杠),否则回退到告警自身的完整 URL;MessageKey 会优先使用元数据中的 canonicalAlertKind 拼接 .<type>(对应"规范告警"的 <kind>.<type> 键);TenantID/TenantName 来自 TenantIdentity()。
3.3 模板辅助函数
| 辅助函数 | 说明 |
|---|---|
title |
首字母大写 |
upper |
转大写 |
lower |
转小写 |
printf |
Go 的格式化输出,如 {{printf "%.1f" .Value}} |
urlquery / urlencode |
URL 查询参数编码 |
urlpath / pathescape |
URL 路径转义 |
jsonString |
安全地将字符串值嵌入 JSON 载荷 |
jsonString 是内嵌字符串值的推荐方式:它转义引号、反斜杠与控制字符,但不会给值再包一层引号,因此你可以写出 "text": "{{.Message | jsonString}}",即使消息内容包含 " 或换行也能保持 JSON 合法。Pulse 内置的各个服务模板都大量使用它(例如 Slack、Teams、Gotify 模板),自定义模板中应优先使用它而不是手动转义。
3.4 服务特定说明
- Telegram:必须将
chat_id放在 URL 查询串中(如?chat_id=<CHAT_ID>)。模板中{{.ChatID}}从 URL 查询串自动填充。 - PagerDuty:需将
routing_key设置为 Webhook 配置中的自定义字段(或请求头)。 - Pushover:必须添加
token与user两个自定义字段。旧的app_token/user_token输入会自动迁移。可选字段还包括sound(如spacealarm、siren、tugboat)、priority(-2 到 2,可覆盖按严重度推断的默认值)、device。 - ntfy:在服务选择器中先选择 ntfy 再输入主题 URL;只有当你希望发送自定义 JSON 载荷时,才让服务保持为 Generic。ntfy 模板按告警严重度生成
CRITICAL/WARNING/INFO纯文本,并可通过自定义请求头(如Authorization: Bearer YOUR_TOKEN)做鉴权;触发时的Tags请求头由 notifications.go 动态构造(<severity>,pulse,<type>),恢复时使用white_check_mark,pulse,resolved。
3.5 示例载荷
{
"text": "Alert: {{.Level}} - {{.Message}}",
"value": {{.Value}}
}
四、投递契约(Delivery Contract)
以下字段与行为是稳定的,工单路由类集成可以依赖它们。
事件(Events):{{.Event}} 只会是 "alert" 或 "resolved",不存在独立的 "info" 事件类别。恢复投递取决于 Notify on resolve(恢复通知开关)以及该次告警与目标在触发投递上是否成功(需要触发投递的成功回执)。不要假设每个配置的 Webhook 都会同时收到两种事件。
严重度(Severity):指标类告警通常使用 "warning" 或 "critical",信息类条件可用 "info"。事件与严重度是独立的:一条 info 级别的触发告警,其事件依然是 "alert"。对未识别的 level 应保留并标记,而不是静默丢弃。最低严重度等其他投递策略仍然生效。
告警类型(Alert type):{{.Type}} 是触发告警的指标或条件,例如 cpu、memory、disk、diskRead、diskWrite、networkIn、networkOut、connectivity 等。告警 ID({{.ID}})用于关联触发与恢复,但同一条件再次触发时 ID 可被复用,因此它不是唯一的事件单或投递 ID。
消息键(Message key):{{.MessageKey}} 是稳定、语言无关的条件键,用于重建或翻译通知。规范告警使用 <kind>.<type>(例如 metric-threshold.disk);较老的告警路径回退到 {{.Type}}。当接收系统需要为触发/恢复事件或不同资源类别准备不同文案时,将其与 {{.Event}}、{{.ResourceType}} 组合使用。与数字型消息索引不同,符号键在新增告警类型时不会变化。其实现逻辑见 notifications.go。
租户身份(Tenant identity):在多租户组织和 MSP 客户端运行时中,{{.TenantID}} 与 {{.TenantName}} 标识是哪个租户触发了告警。客户端运行时从 PULSE_TENANT_ID / PULSE_TENANT_NAME 环境变量获取身份(见 notifications.go);共享进程的组织会自动盖章组织 ID 与显示名。
资源标签路由(Resource tag routing):在 告警(Alerts)→ 通知(Notifications) 中,邮件和每个告警 Webhook 都可以限定只接收带有指定标签的资源告警。空的过滤条件会接收所有告警。设置多个标签时,可选择 Match all tags(匹配全部)或 Match any tag(匹配任一)。标签匹配忽略大小写。Proxmox 标签按原样匹配;Docker 容器与服务标签以 key:value 形式暴露(标签值为空时只有 key)。恢复通知跟随收到触发告警的目标投递,即使资源在恢复前标签发生了变化。路由的核心逻辑 routeNotificationAlerts() 在 internal/notifications/tag_routing.go:恢复事件不重新应用可变的标签/严重度策略,以免因触发与恢复之间路由配置变更而错误抑制恢复通知。
重试(Retries):失败投递按指数退避重试。持久化通知队列每条通知最多进行 3 次投递尝试;配置了传输层重试的 Webhook 在每次尝试内还会额外增加最多 3 次 HTTP 重试(从 1 秒开始翻倍,上限 30 秒,HTTP 429 时遵守 Retry-After)。因此接收方可能多次看到同一条逻辑事件。对应常量见 notifications.go(WebhookInitialBackoff = 1 * time.Second、WebhookMaxBackoff = 30 * time.Second),可重试状态码分类(500+、408、421、423、425、429)在 internal/notifications/webhook_retry_test.go 中有完整测试覆盖。
关联头(Correlation header):告警 Webhook 携带 X-Pulse-Event-ID,格式为 <alertID>:<event>(例如 a1b2c3:alert、a1b2c3:resolved)。重试会保留该头,但后续的同条件再次触发、严重度变化与提醒也可能共享它。分组使用主告警的 ID,而不是为每个成员或批次生成唯一 ID。不要仅依据该头或告警 ID + 事件做永久去重,否则可能静默丢弃后续事件单或发生变化的告警组。其构造逻辑见 webhookEventID()(notifications.go)。
签名投递(Signed deliveries):在 Webhook 配置上设置 signingSecret 即可启用 HMAC 签名。签名请求携带:
X-Pulse-Timestamp:发送时刻的 Unix 秒。X-Pulse-Signature:v1=+ 基于timestamp + "." + body计算的十六进制 HMAC-SHA256,密钥为共享密钥。
在解析 JSON 或执行任何动作之前先完成验签:以字节形式读取原始 body,读取完整的 X-Pulse-Timestamp 与 X-Pulse-Signature 头值;拒绝缺失或重复的签名头。不要重新序列化 JSON、不要裁剪 body,也不要信任载荷中的时间戳而非请求头。源码实现见 notifications.go(签名头在自定义头之后设置,用户自定义头无法覆盖它们)与 signWebhookPayload()(notifications.go);对应的行为测试(含"签名头优先于自定义头")在 internal/notifications/webhook_signing_test.go。
下面的 Python 示例接受与接收方时钟相差 5 分钟以内的时间戳、拒绝格式错误的请求头,并以常量时间比较 HMAC。请保持两端时钟同步;共享密钥应从接收方的私有配置中加载,绝不能来自请求、命令行参数或日志。Pulse 会裁剪其配置密钥两端的空白,验证方也应同样处理。空密钥永远不能通过认证。
import hashlib
import hmac
import re
import time
MAX_SKEW_SECONDS = 300
def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
secret = secret.strip()
if not secret or not isinstance(body, bytes):
return False
if not isinstance(timestamp, str) or re.fullmatch(r"[0-9]{1,12}", timestamp) is None:
return False
if not isinstance(signature, str) or re.fullmatch(r"v1=[0-9a-f]{64}", signature) is None:
return False
if abs(time.time() - int(timestamp)) > MAX_SKEW_SECONDS:
return False
expected = "v1=" + hmac.new(
secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
时间窗口能拒绝旧的捕获,但不是对每次重放都有效:同一签名请求可在窗口内多次到达,而 Pulse 对每次重试都使用当时的发送时间签名。验签后,请按下文"接收方关联与去重"的规则做原子去重,而不是依据签名、发送时间戳或告警 ID 单独去重。alert 与后续的 resolved 是两个不同事件,不是重复项。X-Pulse-Event-ID 是实用的关联提示,但不受 HMAC 保护:不要让被篡改的头绕过对"其他方面完全相同的签名事件"的去重。下方完整 PSA 示例载荷就为每个成员包含了一次出现的身份标识。有效的 HMAC 只证明完整性,不代表处理成功;接收方仍需保留正常的持久化处理与重试机制。诊断被拒请求时,绝不要记录密钥或完整携带凭据的请求。
密钥通过 API 是只写的:列表响应会遮蔽它,而回显掩码占位符的更新会保留原存储密钥。
POST /api/notifications/webhooks
Content-Type: application/json
{
"name": "PSA Bridge",
"url": "https://psa.example.com/inbound/pulse",
"service": "generic",
"enabled": true,
"signingSecret": "<random 32+ byte secret>"
}
4.1 接收方关联与去重
请将工单关联与"抑制重复处理"分开处理:
- 将持久化的接收方记录范围限定在已配置的发送方与目标以及租户,而不是仅凭资源名或告警 ID。验签后从已认证载荷的字段读取身份,并在接收方重启后保留。租户字段是上下文,不是可在任意账户中执行操作的授权。
- 对正常的排队触发与恢复通知,请使用
{{.Alerts}}中的每一个成员,而不只是主{{.ID}}。下面完整 PSA 模板包含每个成员的alertId与全精度 UTCstartedAt,它们标识一次可观察的出现;相同 ID 的更晚开始必须作为新一次出现处理。触发与恢复共用同一条出现记录,因此一条延迟到达的旧恢复不得关闭更新的事件单。 - 在该记录内,要同时处理
event与严重度。warning 升级为 critical 是一次更新,不是重复的 warning。请明确决定提醒是否更新既有工单;不要为每次重试再开一张工单,也不要丢弃严重度升级。告警组可以在头不变的情况下改变成员:即使主告警不变,也要处理每一个成员。 - 主
{{.StartTime}}字符串只有整秒精度。{{.Alerts}}中成员的StartTime是 Go 时间,可以按下述方式格式化为含小数秒的值。不要假设较短的字符串是全局唯一的。测试或遗留载荷可能缺少成员身份;请把不完整或含混的事件保留给对账,而不是静默当作重复。仅用"发送测试(Send test)"不能验证这个生命周期。 - 原子地提交接收方状态与工单动作,或使用工单系统持久化的幂等操作。不要在其动作成功之前把事件标记为已处理。精确签名字节的重放可以单独拒绝,但队列重试可能产生新的 body 或新的发送时间戳:仅对这些做哈希并不是逻辑事件去重。这个遗留头中不存在通用的 exactly-once 键。
请在受控的测试环境中验证以下场景:触发、重试、warning 升 critical、恢复、同一条件的再次发生、多告警组的成员变化。在启用自动动作前检查实际工单与接收方重启行为。不要为了该测试导致生产故障或通知风暴。
五、安全
- 私有 IP:默认情况下,发往私有 IP 的 Webhook 会被拦截。可在 设置(Settings)→ 系统(System)→ 网络(Network)→ Webhook 安全(Webhook Security) 中放行。
- 请求头(Headers):可在 Webhook 配置中追加自定义请求头(例如
Authorization: Bearer ...)。 - 签名(Signing):当接收方支持验签时,优先使用
signingSecret(见上文)而不是裸 bearer 头——它认证的是载荷本身,而不只是连接。
从源码看,ValidateWebhookURL()(notifications.go)实现了完整的 SSRF 防护:URL 必须为 http/https、禁止 userinfo、禁止 unspecified 与 localhost/loopback 地址、禁止 link-local 地址(169.254. 与 fe80: 前缀)、要求 DNS 解析成功并对所有解析出的 IP 检查私有范围(支持 CIDR 白名单,ParseAllowedPrivateCIDRs/ApplyAllowedPrivateCIDRs 在 notifications.go)。另外,Webhook 请求使用 30 秒超时(WebhookTimeout)并将响应读取限制为 1 MB(WebhookMaxResponseSize,notifications.go);诊断日志中的 URL 会通过 RedactWebhookURLSecrets 遮蔽内嵌凭据(见 internal/notifications/webhook_url_redaction.go)。
六、审计 Webhooks(Pro / 旧版 Pro+ / Cloud)
Pro、旧版 Pro+ 与 Cloud 版本支持面向安全事件合规的专用审计 Webhook。与告警通知不同,这些 Webhook 投递的是每次安全相关动作(登录、配置变更、组映射)的原始签名 JSON 载荷。
设置步骤:
- 进入 设置(Settings)→ 安全(Security)→ 审计 Webhooks(Audit Webhooks)。
- 添加你的端点 URL(例如
https://siem.corp.local/ingest/pulse)。
安全:审计 Webhook 异步分发。载荷包含 signature 字段,可用 Pulse 数据目录中加密存储的实例级 HMAC 密钥(.audit-signing.key)验证。没有 PULSE_AUDIT_SIGNING_KEY 覆盖项。
对应的 API 处理器 HandleGetWebhooks / HandleUpdateWebhooks 位于 internal/api/activity_audit_handlers.go,更新接口对请求体做 64 KB 上限限制,并对每个 URL 执行与告警 Webhook 相同的安全校验(仅 http/https、SSRF 防护)。
七、提供商托管的 MSP Webhooks
完整提供商运维指南(拓扑、入口隔离、报告)见 docs/MSP.md。
提供商托管的 MSP 为每个客户工作区运行一个隔离的 Pulse 运行时。这意味着告警路由与 Webhook 目标配置在客户端运行时内部,而不是一张共享的跨客户端告警表。客户端 A 的 Webhook 只会看到客户端 A 的告警,因为客户端 A 拥有自己的 Pulse 运行时、数据、令牌与通知配置。
内置 Webhook 模板包含 Gotify、PagerDuty、Slack 与 Generic。对接受自定义入站载荷的系统(包括 ConnectWise 及类似的 PSA/ITSM 工具),请使用 Generic Webhook。这是 Webhook 路由,不是定制的 PSA 集成。
典型 MSP 设置:
- 从 Pulse Account 打开客户端工作区。
- 在 告警(Alerts)→ 通知(Notifications) 中添加该客户端的通知目标。
- 根据客户端或提供商团队希望的告警落点选择 Gotify、PagerDuty、Slack 或 Generic。
- 让每个目标限定在客户端运行时内,确保告警载荷与恢复事件永远不会进入另一个客户端的工作流。
八、多租户组织集成
在共享进程多租户模式下(自托管且设置 PULSE_MULTI_TENANT_ENABLED=true,并持有带 multi_tenant 能力的 Enterprise 许可证),告警与通知目标按组织隔离。每条告警与每个 Webhook 请求都会解析出一个组织,并且只操作该组织自身的告警状态与 Webhook 配置。该能力对应的环境变量定义见 internal/config/config.go,多租户开关与许可证门控见 internal/api/middleware_license.go 与 internal/api/middleware_tenant.go。
它适用于一位所有者隔离内部站点、部门、团队或环境。它不是面向独立客户业务的规范 Pulse MSP 模型——MSP 使用各自运行时边界隔离的客户端工作区。
请求对应的组织按以下顺序解析:
X-Pulse-Org-ID: <orgID>请求头(API 客户端或内部中间件应这样指定目标组织)。pulse_org_id会话 Cookie(浏览器会话)。- 绑定组织的 API 令牌(绑定到单个组织的令牌无需请求头)。
- 回退:
default组织。
挂起或待删除的组织返回 403,未知组织 ID 返回 400。该解析顺序在 internal/api/middleware_tenant.go 中以注释形式明确列出。
8.1 将组织告警接入外部系统
存在两种集成模型。当工单/事件应自动开闭时,推送模型通常是更合适的选择。
推送(推荐):每个组织一个出站 Webhook。 为每个组织创建一个 Generic Webhook,指向外部系统的入站端点(ITSM/PSA 入站 Webhook、邮件连接器或打开服务工单的中间件)。用自定义模板将 JSON 塑形以匹配接收系统的 schema(见上文"自定义 JSON 模板")。桥接可在 alert 时开单或更新工单、在 resolved 时关闭该次出现,前提是满足上文"投递契约"的条件。在设置表单中以自定义请求头添加认证,并保持其值私有。
可以从界面按组织配置(告警(Alerts)→ 通知(Notifications)→ 添加 Webhook(Add Webhook)),也可以使用绑定组织的管理员令牌编程创建:
POST /api/notifications/webhooks
X-Pulse-Org-ID: acme-corp
Authorization: Bearer <token with settings:write>
Content-Type: application/json
{
"name": "ConnectWise (Acme)",
"url": "https://psa.example.com/inbound/pulse",
"method": "POST",
"service": "generic",
"enabled": true,
"headers": { "Authorization": "Bearer <psa-token>" },
"template": "{\"summary\":\"{{.Level | jsonString}}: {{.ResourceName | jsonString}} {{.Message | jsonString}}\",\"event\":\"{{.Event | jsonString}}\",\"alertId\":\"{{.ID | jsonString}}\",\"startedAt\":\"{{.StartTime | jsonString}}\"}"
}
具体工单字段因平台而异(ConnectWise、Autotask、Halo 等各有各的入站格式),请将模板映射到目标平台的契约。这个简短示例只携带主告警与整秒级开始时间。对于处理真实分组通知的桥接,请使用下方"成员感知"的模板,不要用短示例作为 exactly-once 键。
8.2 样例 PSA 载荷
面向正常排队触发与恢复通知的更完整模板,包含租户上下文以及每个成员的出次、严重度与条件。主字段只是便捷的摘要上下文,并非整批数据:
{
"event": "{{.Event | jsonString}}",
"alertId": "{{.ID | jsonString}}",
"messageKey": "{{.MessageKey | jsonString}}",
"severity": "{{.Level | jsonString}}",
"alertType": "{{.Type | jsonString}}",
"tenantId": "{{.TenantID | jsonString}}",
"tenantName": "{{.TenantName | jsonString}}",
"resource": "{{.ResourceName | jsonString}}",
"resourceType": "{{.ResourceType | jsonString}}",
"node": "{{.Node | jsonString}}",
"summary": "{{.Message | jsonString}}",
"value": {{.Value}},
"threshold": {{.Threshold}},
"startedAt": "{{.StartTime | jsonString}}",
"duration": "{{.Duration | jsonString}}",
"alertCount": {{.AlertCount}},
"alerts": [{{$comma := ""}}{{range .Alerts}}{{if .}}{{$comma}}
{
"alertId": "{{.ID | jsonString}}",
"startedAt": "{{.StartTime.UTC.Format "2006-01-02T15:04:05.999999999Z07:00" | jsonString}}",
"severity": "{{.Level | jsonString}}",
"alertType": "{{.Type | jsonString}}",
"resourceId": "{{.ResourceID | jsonString}}",
"resource": "{{.ResourceName | jsonString}}",
"summary": "{{.Message | jsonString}}"
}{{$comma = ","}}{{end}}{{end}}
]
}
某条 critical 告警的主摘要(模板同时会输出 alerts 成员数组):
{
"event": "alert",
"alertId": "f3a9c2d1",
"severity": "critical",
"alertType": "cpu",
"tenantId": "client-acme",
"tenantName": "Acme Corp",
"resource": "web-01",
"node": "pve1",
"summary": "CPU usage 95.2% exceeds threshold 90%",
"value": 95.2,
"threshold": 90,
"startedAt": "2026-06-10T14:03:00Z",
"duration": "5m"
}
warning 告警与之完全相同,只是 "severity": "warning"。请同样映射 info 等信息级别——两级优先级映射无法覆盖所有条件。
resolved 事件保留原始成员的 alertId 与 startedAt,让桥接关闭该次出现的工单,而不是关闭同 ID 的后来事件单。其主摘要为:
{
"event": "resolved",
"alertId": "f3a9c2d1",
"severity": "critical",
"alertType": "cpu",
"tenantId": "client-acme",
"tenantName": "Acme Corp",
"resource": "web-01",
"node": "pve1",
"summary": "web-01 on pve1 is now healthy",
"value": 95.2,
"threshold": 90,
"startedAt": "2026-06-10T14:03:00Z",
"duration": "22m"
}
针对 ConnectWise:将 Webhook 指向 ConnectWise 入站 API 回调(或调用 ConnectWise REST API 的中间件)。将每个成员的严重度映射到工单优先级,将租户映射到配置的公司。将 signingSecret 与接收方关联规则结合使用,而不是仅依赖请求头去重。在将桥接视为生产就绪之前,请先验证目标平台的处理与恢复行为。
拉取(Pull,轮询):组织级只读 API。 为每个组织签发 monitoring:read 令牌并轮询该组织的告警。发送 X-Pulse-Org-ID(或依赖绑定组织的令牌)即可只拿到该组织的数据:
GET /api/alerts/active—— 该组织当前触发的告警。GET /api/alerts/history—— 该组织的历史告警。
需要从 PSA 侧确认或清除时,使用 monitoring:write 令牌:POST /api/alerts/acknowledge 与 POST /api/alerts/clear。
8.3 作用域与目标汇总
| 动作 | 端点 | 作用域 |
|---|---|---|
| 创建 / 更新 / 删除组织级 Webhook | POST / PUT / DELETE /api/notifications/webhooks |
settings:write(管理员) |
| 列出组织级 Webhook | GET /api/notifications/webhooks |
settings:read(管理员) |
| 读取活跃 / 历史告警 | GET /api/alerts/active、GET /api/alerts/history |
monitoring:read |
| 确认 / 清除告警 | POST /api/alerts/acknowledge、POST /api/alerts/clear |
monitoring:write |
使用 X-Pulse-Org-ID: <orgID> 请求头或绑定组织的 API 令牌来指定目标组织。完整的端点与令牌参考见 docs/API.md。
九、写在最后:投产前的自检清单
无论采用哪种集成方式,投产前都建议对照以下几点核对:
- 事件语义:
alert与resolved是两个事件,恢复依赖"触发投递成功回执 + Notify on resolve",不要假定每个目标都会收到两类事件。 - 去重键:
X-Pulse-Event-ID、alertId都不是全局 exactly-once 键;用"发送方 + 目标 + 租户"作为持久记录范围,用每个成员的alertId+ 全精度startedAt标识一次出现,并同时考虑严重度升级与组成员变化。 - 验签顺序:先以原始字节验签(时间窗口内拒绝旧捕获),再解析载荷与执行动作;密钥走接收方私有配置,日志中永不出现。
- 安全边界:Webhook 目标受私有 IP/SSRF 防护约束,内网端点需在 Webhook 安全设置中显式放行;自定义头无法覆盖签名头。
- 测试覆盖:在受控环境演练触发、重试、warning→critical、恢复、同条件复发与多告警组变化,再启用自动化开单/关单。