跳转到主要内容
配置故障 Webhook，当故障发生特定操作（如触发、关闭）时，系统通过 HTTP 回调您配置的地址。回调内容将包含故障最新关键信息，您可以与自研工具进行集成。

​
一、事件类型

目前支持以下事件类型，未来可能会增加。
事件类型释义
i_new创建故障（自动或手动创建）
i_assign分派故障（自动或手动分派）
i_a_rspd添加处理人
i_snooze手动暂缓故障
i_wake取消暂缓故障
i_ack手动认领故障
i_unack取消认领故障
i_storm触发风暴提醒
i_custom触发自定义操作
i_rslv关闭故障（自动或手动关闭）
i_reopen重新打开故障
i_merge手动合并故障
i_comm添加评论
i_r_title更新故障标题
i_r_desc更新故障描述
i_r_impact更新故障影响
i_r_rc更新故障根因
i_r_rsltn更新故障解决办法
i_r_severity更新故障严重程度
i_r_field更新故障自定义字段

​
二、推送描述

​
请求方式

POST, Content-Type:“application/json”

​
请求 Payload：

字段类型必含释义
event_timeint64是事件发生毫秒时间戳
event_typestring是事件类型，枚举值见事件类型
event_idstring是事件 ID，同一个事件可能因为超时等原因重试多次，接收方需要能够去重
personPerson否操作人，仅人为动作时存在
incidentIncident是故障详情
Person:
字段类型必含释义
person_idint64是人员 ID
person_namestring是人员名称
emailstring是邮件地址
Responder:
字段类型必含释义
person_idint64是人员 ID
person_namestring是人员名称
emailstring是邮件地址
assigned_atint64否分派时间
acknowledged_atint64否认领时间
Incident:
字段类型必含释义
incident_idstring是故障 ID
titlestring是故障标题
descriptionstring否故障描述
impactstring否故障影响
root_causestring否故障根本原因
resolutionstring否故障解决办法
incident_severitystring是严重程度，枚举值：Critical，Warning，Info
incident_statusstring是故障状态，枚举值：Critical，Warning，Info，Ok
progressstring是处理进度，枚举值：Triggered，Processing，Closed
created_atint64是创建时间
updated_atint64是更新时间
start_timeint64是触发时间，Unix 秒时间戳
last_timeint64否最新事件时间，关联告警中的最新事件推送时间，Unix 秒时间戳，默认为 0
end_timeint64否恢复时间，关联的告警全部恢复时，故障也会自动恢复，Unix 秒时间戳，默认为 0
ack_timeint64否首次认领时间，故障可被多人认领，此时间为最早的认领时间。Unix 秒时间戳，默认为 0
close_timeint64否关闭时间，end_time代表故障恢复时间，close_time代表处理进度的关闭时间，故障恢复时会同时关闭，故障关闭时不影响故障恢复。Unix 秒时间戳，默认为 0
snoozed_beforeint64否暂缓截止时间
labelsmap[string]string否标签 KV，Key 和 Value 均为字符串。手动创建时无此信息，自动创建时为聚合的第一条告警的标签信息
fieldsmap[string]interface否自定义字段 KV，Key 为字符串，Value 可能为任意类型，取决于字段类型
creatorPerson否创建人员信息，仅手动创建故障时存在
closerPerson否关闭人员信息，仅手动关闭故障时存在
responders[]Responder否处理人员信息列表，仅故障被分派后存在。对于i_new事件，此值可能为空
alert_cntint64否关联告警个数
channel_idint64否协作空间ID，为0代表不属于任何空间
channel_namestring否协作空间名称
detail_urlstring是详情地址
group_methodstring否聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合

​
请求响应

HTTP status code 为 200，认为推送成功。

​
请求示例

curl -X POST 'https://example.com/incident/webhook?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
    "event_id":"fac0599a2a25529ba2362c0c184b6cfb",
    "event_time":1689335086948,
    "event_type":"i_new",
    "incident":{
        "account_id":74058170041504,
        "account_name":"头铁科技kk",
        "ack_time":0,
        "alert_cnt":0,
        "assigned_to":{
            "assigned_at":1689335086,
            "escalate_rule_id":"64abb8a687e7984845822139",
            "escalate_rule_name":"默认分派",
            "id":"NBRbNwDSTSMijKXdLtBU3T",
            "layer_idx":0,
            "type":"assign"
        },
        "channel_id":1840312623504,
        "channel_name":"Reduce Noise",
        "close_time":0,
        "created_at":1689335086,
        "creator":{
            "email":"toutie@flashcat.cloud",
            "person_id":1552048792504,
            "person_name":"头铁"
        },
        "creator_id":1552048792504,
        "data_source_id":0,
        "dedup_key":"",
        "description":"",
        "detail_url":"http://10.206.0.17:8567/incident/detail/64b1352e376e32c85c56e25b",
        "end_time":0,
        "equals_md5":"",
        "group_method":"n",
        "impact":"",
        "incident_id":"64b1352e376e32c85c56e25b",
        "incident_severity":"Critical",
        "incident_status":"Critical",
        "labels":{
            "check": "cpu idle low"
        },
        "last_time":1689335086,
        "num":"56E25B",
        "progress":"Triggered",
        "resolution":"",
        "responder_ids":[
            1552048792504
        ],
        "responders":[
            {
                "acknowledged_at":0,
                "assigned_at":1689335086,
                "email":"toutie@flashcat.cloud",
                "person_id":1552048792504,
                "person_name":"头铁"
            }
        ],
        "root_cause":"",
        "snoozed_before":0,
        "start_time":1689335086,
        "title":"ysy028",
        "updated_at":1689335086
    },
    "person":{
        "email":"toutie@flashcat.cloud",
        "person_id":1552048792504,
        "person_name":"头铁"
    }
}' -v

​
三、配置指南

进入 集成中心 → Webhook → 添加或编辑 故障 Webhook 集成。

​
基础设置

填写集成名称和描述，便于后续管理。

​
Webhook 设置

配置项说明
Endpoint接收回调的 HTTP/HTTPS 地址，必须以 http:// 或 https:// 开头
TLS 验证默认启用。关闭后将跳过目标服务器的 TLS 证书验证，适用于测试环境或自签名证书场景
Headers自定义请求头，以 Key-Value 形式添加，支持添加多个
协作空间选择 全部空间 或 部分空间。选择部分空间时，仅该空间下的故障事件会触发回调
事件类型勾选需要订阅的事件类型（参见事件类型），支持全选。仅选中的事件类型会触发回调
关闭 TLS 证书验证可能存在中间人攻击风险，建议仅在测试环境或使用自签名证书时关闭。

​
自定义请求体

默认情况下，系统会按照上述 Payload 结构推送完整的 JSON 数据。如果你的接收方对数据格式有特殊要求，可以通过自定义请求体来重新组织推送内容。 使用 {{字段路径}} 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。 变量语法：
  • 用 . 分隔路径层级，如 {{incident.title}} 引用故障标题
  • 支持数组索引访问，如 {{incident.responders.0.email}} 引用第一个处理人的邮箱
  • 当整个值只有一个变量时（如 "{{incident.labels}}"），会保留原始数据类型（对象、数组、数字等）
  • 当变量与其他文本混合时（如 "故障：{{incident.title}}"），变量会被转为字符串拼接
示例： 将默认 Payload 转为自定义格式推送到企业内部系统： 
{
  "msg_type": "incident",
  "event": "{{event_type}}",
  "content": {
    "id": "{{incident.incident_id}}",
    "name": "{{incident.title}}",
    "severity": "{{incident.incident_severity}}",
    "status": "{{incident.progress}}",
    "channel": "{{incident.channel_name}}",
    "url": "{{incident.detail_url}}",
    "labels": "{{incident.labels}}",
    "responders": "{{incident.responders}}"
  }
}
如果变量路径在默认 Payload 中不存在，系统会保留原始的 {{...}} 文本不做替换。建议先通过调用历史查看实际推送的默认 Payload，确认可用的字段路径。

​
四、调用历史

故障 Webhook 提供完整的调用历史记录，方便你排查推送是否成功以及调试回调接口。

​
查看调用历史

进入故障 Webhook 集成详情页，切换到 调用历史 页签即可查看。

​
筛选与搜索

筛选项说明
时间范围支持选择最近 1 小时、6 小时、1 天、7 天，或自定义时间范围（最多查看最近 7 天的数据）
故障 ID输入故障 ID 进行精确搜索
事件类型按事件类型筛选记录
请求状态按成功或失败筛选

​
历史记录字段

字段说明
触发时间事件触发的时间
事件类型触发的事件类型（如 i_new、i_ack 等）
故障 ID关联的故障 ID，可点击跳转到故障详情
事件 ID本次回调的唯一标识，可用于去重
请求状态成功或失败，附带 HTTP 状态码
耗时请求往返耗时
请求次数包括首次请求和重试次数

​
查看调用详情

点击某条记录的 查看详情，可查看完整的请求和响应信息：
  • Request：包括 Endpoint、Request Headers 和 Request Payload
  • Response：成功时显示 Response Headers 和 Response Body；失败时显示 Error Message

​
五、常见问题

  1. 服务是否有响应超时时间？
    • 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败
  2. 推送失败后是否会持续推送？
针对特定的网络错误，会进行重试，最多重试1次:
  • context deadline exceeded (排除 awaiting headers)
  • i/o timeout
  • eof
  1. 如何保证推送顺序？
    • 理论上同一个故障的事件是按照时间顺序进行推送，但是重试等情况可能会导致乱序
    • 服务可以根据 event_time 进行过滤，如果已经收到了更晚的事件，可以直接过滤掉更早的事件，每一次推送都会携带最新的、完整的信息，偶尔丢失事件是可以容忍的
  2. 推送来源可信 IP 白名单？
    • 未来可能会更新，请定期查验