Skip to main content
通过标准协议推送自有系统告警事件到 Flashduty，实现告警事件自动化降噪处理。
Flashduty 已经适配了大部分常用告警系统的 webhook 协议，对于这些系统您应该首先使用对应的集成，更加简单方便。本集成提供了一个标准的 HTTP 接口，需要您开发适配。好处是您可以推送任何您想进行 oncall 的告警事件。

​
操作步骤

​
在 Flashduty

您可通过以下两种方式获取集成推送地址，任选其一即可。
如果您只需将告警发往一个协作空间，选择此方式，配置更简单。
  1. 进入 Flashduty 控制台，选择 协作空间，打开一个协作空间
  2. 选择 配置 → 集成数据 → 专属集成，点击 新增一个集成
  3. 选择 标准告警事件 集成，点击 保存，生成卡片。
  4. 打开生成的集成卡片，复制 推送地址
如果您需要根据告警事件的 Payload 将告警路由到不同协作空间，选择此方式。
  1. 进入 Flashduty 控制台，选择 集成中心 → 告警事件
  2. 选择 标准告警事件 集成：
    • 集成名称：为当前集成定义一个名称。
  3. 配置默认路由并选择协作空间；创建后可在 路由 中增加更多规则
  4. 点击 保存，复制生成的 推送地址

​
请求描述

​
请求方式

POST, Content-Type:“application/json”

​
请求参数

​
Headers

​
Query Strings

​
Payload

​
image 结构体

​
请求响应

Data: Error: Code:

​
请求示例

请求：
成功响应：
失败响应：

​
字段映射与值映射

如果您的系统推送的 JSON 格式无法直接匹配上述标准 Payload 结构，可以在集成设置中配置 字段映射 和 值映射，让 Flashduty 自动将任意格式的 JSON 转换为标准告警事件。
配置字段映射后，请求体不再要求固定格式，可以接收任意 JSON 对象，也支持 JSON 数组批量推送（单次最多 100 条）。

​
字段映射

使用 {{变量路径}} 语法引用原始 JSON 中的字段，将其映射到标准告警事件的目标字段。 支持的目标字段： 以上为集成设置中字段映射编辑器支持的目标字段白名单。images 字段在控制台字段映射编辑器中不可选（底层 field_mapping API 本身支持该字段），请在请求 Payload 中直接上报。 变量语法：
  • 用 . 分隔路径层级，如 {{data.severity}} 引用嵌套字段
  • 当整个值只有一个变量时（如 "{{tags}}"），会保留原始数据类型（对象、数组等）
  • 当变量与其他文本混合时（如 "{{host}} - {{check}}"），变量会被转为字符串拼接
labels 的两种映射方式：
  • 通配符展开："labels": "{{tags}}" — 将 tags 对象的所有子字段展开为标签
  • 逐个映射："labels": {"env": "{{tags.env}}", "host": "{{hostname}}"} — 每个标签单独映射
示例： 您的系统推送格式如下：
配置如下字段映射：

​
值映射

当源系统的字段值与 Flashduty 标准不一致时（如严重程度使用 high 而非 Critical），可以配置值映射进行自动转换。 值映射按字段路径分组配置，每个路径下是一个 源值 → 目标值 的映射表。 示例：
配合上面的字段映射，原始 JSON 中的 "severity": "high" 会先通过字段映射提取，再通过值映射转换为 Critical，最终写入 event_status 字段。
所有 {{...}} 变量必须能在原始 JSON 中解析到值，否则请求会报错。建议先用少量数据测试映射配置是否正确。

​
静默检测

在告警集成详情页（编辑与预览）中，基础设置卡片下方提供 静默检测（Heartbeat）配置卡片：在指定时间内未收到有效事件时，系统会生成一条 Warning 告警。

​
最佳实践

  1. 当告警状态发生变更时，向 Flashduty 发送事件
  2. 当告警恢复时，发送一个 status 为 Ok 的事件，来关闭告警。否则，告警将一直处于打开状态。如果您的告警系统没有恢复事件，建议您手动发送恢复事件
  3. 标签是事件的描述，应尽量丰富标签内容（发送时指定，或者通过配置 enrichment 规则来生成新的标签），比如：
    • 告警的发生来源，如 host，cluster，check 或 metric 等
    • 告警的归属信息，如 team，owner 等
    • 告警的类别信息，如 class（api，db，net）

​
常见问题

在 Flashduty
  1. 查看集成是否展示 最新事件时间。如果没有，说明 Flashduty 未收到推送，请先排查您的系统。
  2. 如果您使用 共享集成，请先确认已配置 路由规则。没有路由规则时，系统会拒绝新的推送，因为没有协作空间承接告警。请将路由规则指向目标协作空间。
在您的系统
  1. 确认请求地址与集成详情中的地址完全一致。
  2. 确认您的服务可以访问 api.flashcat.cloud。如果无法访问，请为服务器开通外网，或单独放行 Flashduty 的域名。
  3. 打印 Flashduty 的响应，查看其中的错误信息。
如果完成以上步骤后仍未找到原因，请 携带响应中的 request_id 联系我们。
Flashduty 使用 2 层降噪机制：
  1. 首先对告警 event 进行去重检查，如果您推送的 event 和之前推送的 event 内容完全一致，则新的 event 将被直接丢弃。
  2. 如果新的 event 的状态和描述和其对应的告警的上一条 event 的状态、标题、描述均一致，则新的 event 将被直接丢弃，同时更新归属告警属性。
  3. 新的 event 可能由于匹配到排除、丢弃、抑制或静默规则，而被丢弃。
  4. 当新的 event 触发了新告警，则系统会进入第二层降噪检查，判断新告警是否可以被合并到某个活跃的故障中，如果可以，则只会并入已有的故障，而不会产生新故障。
更多内容请参考 告警降噪。