Webhook 自定义操作

配置故障自定义操作，允许您在故障排查期间，快速调用外部接口，实现故障自愈、信息丰富等任何自定义操作。

一、创建操作

登录 Flashduty 控制台，进入【集成中心-Webhook】
点击添加自定义操作集成
配置操作名称，此名称将以按钮的形式体现在故障详情中
配置管理团队（可选），只有该团队成员可以编辑此集成配置
配置协作空间，可以配置多个，但每个协作空间至多添加五个自定义操作
配置 Endpoint、自定义 Headers
保存，完成

二、推送描述

请求方式

POST, Content-Type:“application/json”

请求 Payload

字段	类型	必含	释义
event_time	int64	是	事件发生`毫秒时间戳`
event_type	string	是	事件类型，固定值`i_custom`
event_id	string	是	事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重`
event_detail	object	否	事件明细，固定结构见下方事件明细
person	Person	否	操作人，仅人为动作时存在
incident	Incident	是	故障详情

Person:

字段	类型	必含	释义
person_id	int64	是	人员 ID
person_name	string	是	人员名称
email	string	是	邮件地址

Responder:

字段	类型	必含	释义
person_id	int64	是	人员 ID
person_name	string	是	人员名称
email	string	是	邮件地址
assigned_at	int64	否	分派时间
acknowledged_at	int64	否	认领时间

AssignedTo:

字段	类型	必含	释义
person_ids	[]int64	否	直接分派的人员 ID 列表，直接分派到指定人员时存在
escalate_rule_id	string	否	分派策略 ID，按分派策略分派时存在
escalate_rule_name	string	否	分派策略名称
layer_idx	int	是	当前分派层级，从 0 开始
type	string	是	分派方式，枚举值：assign（分派）、reassign（改派）、escalate（层级升级）、reopen（重新打开后分派）
id	string	是	分派记录 ID
assigned_at	int64	是	分派时间，Unix 秒时间戳
effective_person_ids	[]int64	否	本次分派最终生效的人员 ID 列表，为直接分派的人员与按分派策略解析出的人员的并集，已去重并按 ID 升序排列

LinkItem:

字段	类型	必含	释义
name	string	是	链接名称
endpoint	string	是	跳转地址，链接集成中配置的模板变量已替换为当前故障的实际值
open_type	string	是	打开方式，枚举值：popup（弹窗）、tab（新标签页）

Image:

字段	类型	必含	释义
src	string	是	图片地址
href	string	是	点击图片的跳转地址，可能为空字符串
alt	string	是	图片说明，可能为空字符串

Incident:

字段	类型	必含	释义
incident_id	string	是	故障 ID
account_id	int64	是	账户 ID
account_name	string	是	账户名称
title	string	是	故障标题
description	string	否	故障描述
impact	string	否	故障影响
root_cause	string	否	故障根本原因
resolution	string	否	故障解决办法
incident_severity	string	是	严重程度，枚举值：Critical，Warning，Info
incident_status	string	是	故障状态，枚举值：Critical，Warning，Info，Ok
progress	string	是	处理进度，枚举值：Triggered，Processing，Closed
created_at	int64	是	创建时间
updated_at	int64	是	更新时间
start_time	int64	是	触发时间，Unix 秒时间戳
last_time	int64	否	最新事件时间，关联告警中的最新事件推送时间，Unix 秒时间戳，默认为 0
end_time	int64	否	恢复时间，关联的告警全部恢复时，故障也会自动恢复，Unix 秒时间戳，默认为 0
ack_time	int64	否	首次认领时间，故障可被多人认领，此时间为最早的认领时间。Unix 秒时间戳，默认为 0
close_time	int64	否	关闭时间，end_time代表故障恢复时间，close_time代表处理进度的关闭时间，故障恢复时会同时关闭，故障关闭时不影响故障恢复。Unix 秒时间戳，默认为 0
snoozed_before	int64	否	暂缓截止时间
labels	map[string]string	否	标签 KV，Key 和 Value 均为字符串。手动创建时无此信息，自动创建时为聚合的第一条告警的标签信息
fields	map[string]interface	否	自定义字段 KV，Key 为字符串，Value 可能为任意类型，取决于字段类型
creator	Person	否	创建人员信息，仅手动创建故障时存在
closer	Person	否	关闭人员信息，仅手动关闭故障时存在
creator_id	int64	是	创建人 ID，仅手动创建故障时非 0
closer_id	int64	是	关闭人 ID，仅手动关闭故障时非 0
owner_id	int64	是	负责人 ID，保留字段
responders	[]Responder	否	处理人员信息列表，仅故障被分派后存在
assigned_to	AssignedTo	否	分派信息，仅故障被分派后存在
dedup_key	string	是	去重键，聚合标识，自动创建时有效，手动创建时为空字符串
alerts	[]Alert	否	关联告警列表，无关联告警时不返回该字段
alert_cnt	int64	否	关联告警个数
active_alert_cnt	int64	否	保留字段，当前推送恒为 0，请使用 alert_cnt
integration_id	int64	是	首个关联告警的集成 ID，无关联告警时为 0
integration_ids	[]int64	否	关联告警来源的集成 ID 列表
integration_types	[]string	否	关联告警来源的集成类型列表
data_source_id	int64	是	兼容保留字段（Deprecated），同 integration_id，请使用 integration_id
data_source_ids	[]int64	否	兼容保留字段（Deprecated），同 integration_ids
num	string	是	故障短标识，取故障 ObjectID 最后 6 位十六进制并大写，例如 `054D57`，在控制台界面中显示。可作为查询故障详情 API 的替代参数（与 `incident_id` 二选一），同一账号下不唯一，查询时返回最新创建的匹配记录
channel_id	int64	否	协作空间ID，为0代表不属于任何空间
channel_name	string	否	协作空间名称
channel_status	string	是	协作空间状态，枚举值：enabled、disabled，故障不属于任何空间时为空字符串
team_id	int64	否	协作空间所属团队 ID，无归属团队时为 0
detail_url	string	是	详情地址
silence_url	string	是	快速静默页面地址
links	[]LinkItem	否	保留字段，自定义操作场景不返回，请使用故障 Webhook 获取
group_method	string	否	聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合
has_unfinished_work_item	bool	是	是否还有未完成的行动项或跟进项
post_mortem_id	string	是	关联复盘报告 ID，由关联故障集合确定性生成，无关联时为 `"0"`
images	[]Image	是	故障图片列表，无图片时为 null

Alert:

字段	类型	必含	释义
alert_id	string	是	告警 ID
account_id	int64	是	账户 ID
integration_id	int64	是	集成 ID
integration_name	string	是	保留字段，自定义操作场景恒为空字符串，请使用 integration_id
integration_type	string	是	保留字段，自定义操作场景恒为空字符串
integration_ref_id	string	否	自定义操作场景不返回该字段
data_source_id	int64	是	兼容保留字段（Deprecated），同 integration_id，请使用 integration_id
data_source_name	string	是	兼容保留字段（Deprecated），同 integration_name，恒为空字符串
data_source_type	string	否	兼容保留字段（Deprecated），同 integration_type，不返回该字段
data_source_ref_id	string	是	兼容保留字段（Deprecated），同 integration_ref_id，恒为空字符串
channel_id	int64	是	协作空间 ID
channel_name	string	是	保留字段，自定义操作场景恒为空字符串
channel_status	string	是	保留字段，自定义操作场景恒为空字符串
title	string	是	告警标题
title_rule	string	否	标题生成规则
description	string	否	告警描述
alert_key	string	是	告警关联依据
alert_severity	string	是	严重程度，枚举值：Critical，Warning，Info
alert_status	string	是	告警状态，枚举值：Critical，Warning，Info，Ok
progress	string	是	处理进度，枚举值：Triggered，Closed
created_at	int64	是	创建时间
updated_at	int64	是	更新时间
start_time	int64	是	首次触发时间（平台接收到的首个事件的时间），Unix 秒时间戳
last_time	int64	是	最新事件时间（平台接收到的最新事件时间），Unix 秒时间戳
end_time	int64	否	告警恢复时间（平台上一次接收到结束类型事件的时间），Unix 秒时间戳，默认为 0
close_time	int64	否	关闭时间，不同于 end_time，这个是处理进度的关闭，不代表告警真的恢复。Unix 秒时间戳，默认为 0
ever_muted	bool	是	是否曾被静默策略静默
responder_name	string	是	保留字段，当前恒为空字符串，处理人信息请从故障维度获取
responder_email	string	是	保留字段，当前恒为空字符串
labels	map[string]string	否	标签 KV，Key 和 Value 均为字符串
event_cnt	int64	否	关联事件个数
images	[]Image	是	告警图片列表，无图片时为 null
incident	IncidentShort	否	所属故障，自定义操作场景不返回该字段

IncidentShort:

字段	类型	必含	释义
incident_id	string	是	故障 ID
title	string	否	故障标题，可能不返回

event_detail（i_custom 固定结构）：

字段	类型	必含	释义
integration_id	int64	否	触发的自定义操作集成 ID
integration_name	string	否	触发的自定义操作集成名称

请求响应

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

请求示例

curl -X POST 'https://example.com/incident/action?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
    "event_detail":{
        "integration_id":1234567890123,
        "integration_name":"重启主机"
    },
    "event_id":"fac0599a2a25529ba2362c0c184b6cfb",
    "event_time":1700208013988,
    "event_type":"i_custom",
    "incident":{
        "account_id":74058170041504,
        "account_name":"头铁科技",
        "ack_time":0,
        "alert_cnt":1,
        "alerts":[
            {
                "account_id":74058170041504,
                "alert_id":"6551f37f8713372ad1054d54",
                "alert_key":"asdflasdfl2xzasd112621",
                "alert_severity":"Critical",
                "alert_status":"Critical",
                "channel_id":1973372625504,
                "channel_name":"",
                "channel_status":"",
                "close_time":0,
                "created_at":1699869567,
                "data_source_id":2398086111504,
                "data_source_name":"",
                "data_source_ref_id":"",
                "description":"cpu.idle < 20%",
                "end_time":0,
                "event_cnt":1,
                "ever_muted":false,
                "images":null,
                "integration_id":2398086111504,
                "integration_name":"",
                "integration_type":"",
                "labels":{
                    "check":"自定义字段测试",
                    "cluster":"nj",
                    "metric":"node_cpu_seconds_total",
                    "resource":"es.nj.01",
                    "service":"engine"
                },
                "last_time":1699869562,
                "progress":"Triggered",
                "responder_email":"",
                "responder_name":"",
                "start_time":1699869562,
                "title":"nj / es.nj.01 - 自定义字段测试",
                "title_rule":"$cluster::$resource::$check",
                "updated_at":1699869576
            }
        ],
        "assigned_to":{
            "assigned_at":1699869576,
            "escalate_rule_id":"6509344bc1d50d723ca04986",
            "escalate_rule_name":"策略5",
            "id":"VobpBqvTuXgQ7BZzJ2Qu94",
            "layer_idx":0,
            "type":"assign"
        },
        "channel_id":1973372625504,
        "channel_name":"lim_test",
        "channel_status":"enabled",
        "close_time":0,
        "created_at":1699869576,
        "creator":{
            "email":"toutie@flashcat.cloud",
            "person_id":1552048792504,
            "person_name":"头铁"
        },
        "creator_id":1552048792504,
        "data_source_id":2398086111504,
        "dedup_key":"asdflasdfl2xzasd112621",
        "description":"cpu.idle < 20%",
        "detail_url":"http://10.206.0.17:8567/incident/detail/6551f3888713372ad1054d57",
        "end_time":0,
        "equals_md5":"",
        "fields":{
            "impacted_services":[
                "passport",
                "order"
            ],
            "priority":"P3"
        },
        "group_method":"p",
        "has_unfinished_work_item":false,
        "images":null,
        "impact":"",
        "incident_id":"6551f3888713372ad1054d57",
        "incident_severity":"Critical",
        "incident_status":"Critical",
        "integration_id":2398086111504,
        "labels":{
            "check":"自定义字段测试",
            "cluster":"nj",
            "metric":"node_cpu_seconds_total",
            "resource":"es.nj.01",
            "service":"engine"
        },
        "last_time":1699869562,
        "num":"054D57",
        "post_mortem_id":"0",
        "progress":"Triggered",
        "resolution":"",
        "responders":[
            {
                "acknowledged_at":0,
                "assigned_at":1699869576,
                "email":"zhangsan@toutie.com",
                "person_id":1234648032504,
                "person_name":"zhangsan"
            }
        ],
        "root_cause":"",
        "silence_url":"http://10.206.0.17:8567/channel/detail/1973372625504?tab=alertSuppression&fromIncidentId=6551f3888713372ad1054d57",
        "snoozed_before":0,
        "start_time":1699869562,
        "title":"nj / es.nj.01 - 自定义字段测试",
        "updated_at":1699929113
    },
    "person":{
        "email":"zhangsan@toutie.com",
        "person_id":1999632289504,
        "person_name":"zhangsan"
    }
}' -v

三、自定义请求体与值映射

自定义请求体

默认情况下，系统会按照上述 Payload 结构推送完整的 JSON 数据。如果您的接收方对数据格式有特殊要求，可以通过自定义请求体来重新组织推送内容。使用 {{字段路径}} 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。 变量语法：

用 . 分隔路径层级，如 {{incident.title}} 引用故障标题
支持数组索引访问，如 {{incident.responders.0.email}} 引用第一个处理人的邮箱
当整个值只有一个变量时（如 "{{incident.labels}}"），会保留原始数据类型（对象、数组、数字等）
当变量与其他文本混合时（如 "故障：{{incident.title}}"），变量会被转为字符串拼接

示例：

{
  "action": "{{event_type}}",
  "incident_id": "{{incident.incident_id}}",
  "title": "{{incident.title}}",
  "severity": "{{incident.incident_severity}}",
  "url": "{{incident.detail_url}}",
  "operator": "{{person.person_name}}",
  "labels": "{{incident.labels}}"
}

如果变量路径在默认 Payload 中不存在，系统会保留原始的 {{...}} 文本不做替换。建议先通过测试推送查看实际的默认 Payload，确认可用的字段路径。

值映射

通过值映射，可以在自定义请求体的变量解析时自动转换字段值。值映射按字段路径分组配置。 示例：

{
  "incident.incident_severity": {
    "Critical": "P0",
    "Warning": "P1",
    "Info": "P2"
  }
}

配合自定义请求体中的 "severity": "{{incident.incident_severity}}" 使用，当故障严重程度为 Critical 时，推送结果中 severity 字段的值为 P0。未匹配到映射的值将保持原样。

四、使用场景

重启主机

当主机内存或CPU打满，触发主机重启脚本，快速完成主机重启。

信息丰富

当故障发生时，回调您的服务，根据告警详情调取 Tracing、Logging、拓扑等信息，主动调用 Flashduty Open API 来更新故障信息，比如增加标签或设定自定义字段，辅助排障。

回滚变更

当发生故障时，如果确定故障由变更导致，可以直接触发回调到您的部署平台，开启回滚进程，加速故障恢复。

更新 status page

当确定故障影响到线上服务，可以触发外部 status page 更新，及时的通知到您的客户或上下游。

五、常见问题

服务是否有响应超时时间？
- 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败
推送失败后是否会持续推送？

针对特定的网络错误，会进行重试，最多重试1次:

context deadline exceeded (排除 awaiting headers)
i/o timeout
eof

推送来源可信 IP 白名单？
- 47.94.95.118、123.56.8.183、47.94.193.81 和 1.13.19.96（SaaS 版本；私有化部署的推送来源为您自有环境的出口地址，请向您的基础设施团队确认）
- 未来可能会更新，请定期查验

快速开始

产品对比

协作空间

故障管理

故障复盘

状态页

分析看板

集成配置

配置中心

高级功能

集成中心

最佳实践

一、创建操作

二、推送描述

请求方式

请求 Payload

请求响应

请求示例

三、自定义请求体与值映射

自定义请求体

值映射

四、使用场景

重启主机

信息丰富

回滚变更

更新 status page

五、常见问题

​一、创建操作

​二、推送描述

​请求方式

​请求 Payload

​请求响应

​请求示例

​三、自定义请求体与值映射

​自定义请求体

​值映射

​四、使用场景

​重启主机

​信息丰富

​回滚变更

​更新 status page

​五、常见问题

一、创建操作

二、推送描述

请求方式

请求 Payload

请求响应

请求示例

三、自定义请求体与值映射

自定义请求体

值映射

四、使用场景

重启主机

信息丰富

回滚变更

更新 status page

五、常见问题