背景
自动化中，在触发器下方添加 Webhook 操作并触发时，会推送整合后的新版Webhook 格式。
从以前事件与通知系统自动迁移至自动化的配置，会兼容老版 Webhook 格式，但请尽快升级。如果删除了旧配置后重新配置 Webhook，兼容格式不再推送，只推送新版格式。
配置方式
如何配置 Webhook？
在流程图中添加 Webhook 操作即可配置 Webhook。触发时，会推送整合后的新版 Webhook 格式。
250px|700px|reset
对应关系
触发器 | 老版 webhook 事件 | 老版 webhook 对应 eventType | event_type |
创建工作项 250px|700px|reset | 需求创建 | StoryCreated | WorkitemCreateEvent |
| 工作项创建 | EventCreate-{工作项类型} | |
字段值修改 250px|700px|reset | 需求修改 | StoryValueChanged | WorkitemUpdateEvent |
| 工作项修改 | EventUpdate-{工作项类型} | |
终止工作项 250px|700px|reset | 需求终止 | StoryAborted | WorkitemAbortedEvent（工作项终止） WorkitemRestoreEvent（工作项恢复） |
| 工作项终止 | EventAborted-{工作项类型} | |
需求状态修改 250px|700px|reset | 需求状态修改 | StoryStageChanged | WorkitemStatusEvent |
工作项状态修改 250px|700px|reset | 工作项状态更新 | EventUpdateStatus-{工作项类型} | |
任务状态修改 250px|700px|reset | 任务状态修改 | EventUpdateStatus-task | TaskStatusEvent |
任务修改 250px|700px|reset | 任务修改 | EventUpdate-task | TaskUpdateEvent |
角色操作 250px|700px|reset | 需求人员分配 | StoryRoleAssigned | WorkitemPersonAssignedEvent |
| 工作项人员分配 | EventRoleAssigned-{工作项类型} | |
| 节点负责人分配(需求) | WFNodeOwnerChanged | |
| 节点负责人分配(其他工作项) | WFNodeOwnerChanged-{工作项类型} | |
节点状态修改 250px|700px|reset | 节点完成(需求) 节点完成(其他工作项) | WFNodeChecked WFNodeChecked-{工作项类型} | WorkFlowNodeStatusEvent |
| 节点到达(需求) 节点完成(其他工作项) | WFNodeReached WFNodeReached-{工作项类型} | |
| 节点回滚(需求) 节点完成(其他工作项) | WFNodeRollbacked WFNodeRollbacked-{工作项类型} | |
节点排期操作 250px|700px|reset | 节点排期变更(需求) | WFNodeScheduleChanged | WorkFlowNodeScheduleEvent |
| 节点排期变更(其他工作项) | WFNodeScheduleChanged-{工作项类型} | |
评论操作 250px|700px|reset | 需求评论操作 | StoryCommentAdded | WorkitemCommentEvent |
| 工作项评论操作 | EventCommentAdded-{工作项类型} | |
工作项归档 250px|700px|reset | 需求归档 | StoryFinished | WorkitemFinishEvent |
| 工作项归档 | EventFinished-{工作项类型} | |
删除工作项 250px|700px|reset | 需求删除 | StoryDeleted | WorkitemDeleteEvent |
| 工作项删除 | EventDelete-{工作项类型} | |
定时循环 250px|700px|reset | | | TimedTriggerEvent |
动态时间任务 250px|700px|reset | | | DynamicTimeTriggerEvent |
兼容性说明
Webhook 是一种用于实时传递数据的机制，其数据结构可能会随着业务需求的变化而变化。为了确保系统的可扩展性和兼容性，以下是针对 Webhook 数据结构设计的兼容性说明。
- Webhook 数据的基本结构示例如下：
{
"header": {
// 这里可能会新增扩展字段
},
"payload": {
// 这里可能会新增扩展字段
}
// 这里可能会新增扩展字段
}}
- 兼容性策略
- 新增字段：当提供方在数据结构中新增字段时，消费方应能够忽略未识别的字段，而不会影响其正常处理。
- 默认值：消费方可以针对字段设置合理的默认值，确保在提供方未提供该字段的情况下，系统仍能正常运行。
新版webhook对应Body格式
- webhook 设计有幂等串，header -> uuid，可以考虑使用幂等串去重
- webhook 推送后 6s 超时，超时会重试，最大重试次数 3 次
- 接收 webhook 请使用 POST 的方法，以下格式均为 POST 方法的 body 数据
WorkitemCreateEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemCreateEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": { // json结构，基于facade_idl里面workitem结构
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"template_id": 13046, // int，64位, 模板id
"template_type":"", // string，工作项类型(只有需求有)
"pattern": "", // string，模式（节点流、状态流）
"sub_stage": "", // string，仅早期实例涉及，已弃用
"work_item_status": {}, // struct, 状态流工作项的状态, 仅状态流工作项有
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"created_at": 1639548438000, // int，64位，创建时间戳
"created_by": "", // string，创建人的userkey
"current_nodes": [ // json，当前所处的节点, 仅节点流工作项有
{
"id": "state_0",
"name": "进行中",
"owners": [
"6992398322484936706"
]
}
],
"fields": [ // json，工作项字段
{
"field_alias": "owner",
"field_key": "owner",
"field_type_key": "user",
"field_value": interface{}
},
]
}
}}
WorkitemUpdateEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemUpdateEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"changed_fields": [
{
"field_alias": "owner", // 字段对接标识
"field_key": "owner", // 字段key
"field_type_key": "user", // 字段类型
"pre_field_value": interface{}, // 变更前的值
"cur_field_value": interface{} // 变更后的值
},
]
}
}}
WorkitemAbortedEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemAbortedEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"is_aborted": true, // bool，是否终止
"reason": "" // string，终止或者恢复原因
}
}}
WorkitemRestoreEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemRestoreEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"is_aborted": true, // bool，是否终止
"reason": "" // string，终止或者恢复原因
}
}}
WorkitemPersonAssignedEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemPersonAssignedEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"role_owners": [{ // 仅流程角色变更时存在
"role": "",
"add_owners": [], // 新增的owner key
"delete_owners": [] // 删除的owner key
}],
"node_owners": [{ // 仅节点负责人变更时存在
"id": "", // string
"state_key": "", // string
"node_name": "", // string，节点名称
"add_owners": [], // 新增的负责人
"delete_owners": [], // 删除的负责人
}],
"task_owners":[{ // 仅子任务负责人变更时存在
"id": "", // string，子任务id
"name": "", //string，子任务名称
"parent_node_id": "", //string，父节点id
"parent_node_state_key": "", // string，父节点stateKey
"parent_node_name": "", // string，父节点名称
"add_owners": [], // string[], 新增的子任务负责人
"delete_owners": [], // string[], 删除的子任务负责人
}]
}
}}
WorkitemCommentEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemCommentEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"work_item_type_key": "", // string，工作项类型
"comment": "", //string，需求的评论内容
}
}}
WorkitemFinishEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemFinishEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "" // string，工作项类型
}
}}
WorkitemDeleteEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemDeleteEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "" // string，工作项类型
}
}}
WorkitemStatusEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemStatusEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"pre_sub_stage": "", // string，变更前工作项状态，仅节点流工作项冗余
"cur_sub_stage": "", // string，变更后工作项状态，仅节点流工作项冗余
"pre_work_item_status": {
"state_key": "", // string，状态key
"is_archived_state": true, // bool，是否是归档状态
"is_init_state": true, // bool，是否是初始状态
"updated_at": 1111, // 更新时间
"updated_by": "" // 更新人userkey
},
"cur_work_item_status": {
"state_key": "", // string，状态key
"is_archived_state": true, // bool，是否是归档状态
"is_init_state": true, // bool，是否是初始状态
"updated_at": 1111, // 更新时间
"updated_by": "" // 更新人userkey
},
"confirm_form": [{ // 状态流转的表单,仅状态流工作项存在
"field_alias": "owner",
"field_key": "owner",
"field_type_key": "user",
"field_value": interface{}
}]
}
}}
WorkFlowNodeStatusEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkFlowNodeStatusEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "" // string，工作项类型
"pre_sub_stage": "", // 仅在节点变更触发状态变更时存在
"cur_sub_stage": "", // 仅在节点变更触发状态变更时存在
"pre_work_item_status": { // 仅在节点变更触发状态变更时存在
"state_key": "", // string，状态key
"is_archived_state": true, // bool，是否是归档状态
"is_init_state": true, // bool，是否是初始状态
"updated_at": 1111, // 更新时间
"updated_by": "" // 更新人userkey
},
"cur_work_item_status": { // 仅在节点变更触发状态变更时存在
"state_key": "", // string，状态key
"is_archived_state": true, // bool，是否是归档状态
"is_init_state": true, // bool，是否是初始状态
"updated_at": 1111, // 更新时间
"updated_by": "" // 更新人userkey
},
"nodes":[{
"id": ""， // 节点的id
"state_key": "", // 节点的key，等同id，冗余
"node_name": "", // 节点的名称
"pre_status": 1, // 节点的变更前状态
"cur_status": 2, // 节点的变更后状态
"node_form":[{ // 节点表单
"field_alias": "owner",
"field_key": "owner",
"field_type_key": "user",
"field_value": interface{}
},]
}],
"reason": "", //只在回滚的时候有
"status_change_type": "" // Rollback/Reached/Checked <=> 回滚/到达/确认
}
}}
WorkFlowNodeScheduleEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkFlowNodeScheduleEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": {
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"work_item_type_key": "", // string，工作项类型
"nodes": [{ // 需求流程节点的信息
"id": "", // 节点的id
"state_key": "", // 节点的key，等同id，冗余
"node_name": "", // 节点的名称
"node_schedule_change":{ // 节点排期变更信息
"pre_schedule":{
"estimate_start_date": 1111,
"estimate_end_date": 1111,
"points": 111
},
"cur_schedule":{
"estimate_start_date": 1111,
"estimate_end_date": 1111,
"points": 222
}
},
"owner_schedules_change":[{ // 差异化排期的人员排期
"owner": "",
"pre_schedule":{
"estimate_start_date": 1111,
"estimate_end_date": 1111,
"points": 11
},
"cur_schedule":{
"estimate_start_date": 1112,
"estimate_end_date": 1112,
"points": 22
}
}]
}]
}
}}
TaskStatusEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "TaskStatusEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": { // 事件产生的数据
"work_item_id":int, // 任务所挂工作项对应的work_item_id，64位
"work_item_name": "", // 任务所挂工作项对应的名称
"task_id":int, // 任务对应的id，64位
"task_name": "", // 任务名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"pre_status": int,
"cur_status": int,
"relate_state_id": "node_state_0_79697751",// 任务所属节点ID
"related_state_key": "state_0",// 任务所属节点key
"relate_state_name": "", // 任务所属节点名称
}
}}
TaskUpdateEvent
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "TaskUpdateEvent", // string, webhook的event_type
"token": "xxx", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": { // 事件产生的数据
"work_item_id":int, // 任务所挂工作项对应的work_item_id，64位
"work_item_name": "", // 任务所挂工作项对应的名称
"task_id":int, // 任务对应的id，64位
"task_name": "", // 任务名称
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"relate_state_id": "node_state_0_79697751",// 任务所属节点ID
"related_state_key": "state_0",// 任务所属节点key
"relate_state_name": "", // 任务所属节点名称
"updated_at": 1639548775000, // int，64位，更新时间戳
"updated_by": "", // string，更新人的userkey
"changed_fields": [
{
"field_alias": "owner",
"field_key": "owner",
"field_type_key": "user",
"pre_field_value": interface{},
"cur_field_value": interface{}
},
],
//任务排期变更
"nodes": [
{
"id": "", // 节点的id
"state_key": "", // 节点的key，等同id，冗余
"node_name": "", // 节点的名称
"task_schedule": [
{
"actual_work_time": null,
"estimate_end_date": 1719071999999,
"estimate_start_date": 1718899200000,
"owners": [
"7147600751534030867"
],
"points": 1,
"task_id": 79697511,
"task_name": "123"
}
]
}
],
}
}}
TimedTriggerEvent
{
"header": {
"operator": "", // string, 规则的最后更新人
"event_type": "TimedTriggerEvent", // string, webhook的event_type
"token": "xxx", // string，注册webhook填入的token
"uuid": "" // string，幂等串
"rule_name": "" //自动化规则名称
},
"payload": { // 事件产生的数据
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"trigger_at": 1639548775000, // int，64位，本次定时的触发时间戳
"work_items": [
{
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"work_item_type_key": "", // string，工作项类型
},
]
}
}}
DynamicTimeTriggerEvent
{
"header": {
"operator": "", // string, 规则的最后更新人
"event_type": "DynamicTimeTriggerEvent", // string, webhook的event_type
"token": "xxx", // string，注册webhook填入的token
"uuid": "" // string，幂等串
"rule_name": "" //自动化规则名称
},
"payload": { // 事件产生的数据
"project_key": "", // string，空间ID
"project_simple_name": "", // string，空间域名
"trigger_at": 1639548775000, // int，64位，本次定时的触发时间戳
"work_items": [
{
"id": 111, // int，64位，工作项id
"name": "", // string，工作项名称
"work_item_type_key": "", // string，工作项类型
"trigger_fields":[{ // 工作项触发本次定时规则的字段列表
"field_alias": "finish_time",
"field_key": "finish_time",
"field_type_key": "schedule",
"field_value": interface{}
}],
"trigger_nodes":[{ // 工作项触发本次定时规则的节点列表的排期信息
"id": "", // 节点的id
"state_key": "", // 节点的key，等同id，冗余
"node_name": "", // 节点的名称
"node_schedule":{ // 节点总排期
"estimate_start_date": 1111,
"estimate_end_date": 1111,
"points": 111
},
"owner_schedules":[{ // 差异化排期的人员排期
"owner": "",
"estimate_start_date": 1111,
"estimate_end_date": 1111,
"points": 111
}]
}],
"trigger_tasks": [{ // 仅选择“指定子任务排期”时存在
"related_node_id": "", // 任务所属节点ID
"related_node_name": "", // 任务所属节点名称
"tasks": [{ // 任务排期信息
"estimate_end_date": 1111, // 排期开始时间
"estimate_start_date": 1111, // 排期结束时间
"owners": [], // 任务负责人，string数组
"points": 2 // 估分
}]
}],
"trigger_retention_nodes": [{ // 仅选择“指定节点停留时间”时存在
"arrive_at": 1111, // 触发节点到达时间
"state_key": "", // 触发停留时间节点key
"name": "", // 触发停留时间节点名称
"owners": [], // 节点负责人，string数组
}],
"trigger_retention_status": [{ // 仅选择“指定状态停留时间”时存在
"arrive_at": 1111, // 触发状态到达时间
"state_key": "" // 触发停留时间状态key
}]
}
]
}
}}
TaskCreateEvent
{
"header": {
"event_type": "TaskCreateEvent",
"operator": "",
"token": "",
"uuid": "76283b9afefac6fad91132c2ddf2ffc0"
},
"payload": {
"api_owners_schedule": { //排期估分
"estimate_end_date": null,
"estimate_start_date": null,
"owners": [ //负责人userkey
"7147600751534030867"
],
"points": null
},
"created_at": 0,
"created_by": "7147600751534030867",
"project_key": "639068b0bd50cb571bd8591e",
"project_simple_name": "",
"relate_state_id": "node_state_0_79697751",
"relate_state_name": "", //节点名称
"related_state_key": "state_0", //节点key
"task_id": 79697511, //任务ID
"task_name": "",
"work_item_id": 79697751, //实例ID
"work_item_name": "hook测试",
"work_item_type": "story"
}
}}
TaskDeleteEvent
{
"header": {
"event_type": "TaskDeleteEvent",
"operator": "",
"token": "",
"uuid": "7ea6acf9357906a04ed1b7b1c8877e9b"
},
"payload": {
"api_owners_schedule": {
"estimate_end_date": 1719071999999,
"estimate_start_date": 1718899200000,
"owners": [
"7147600751534030867"
],
"points": 1
},
"project_key": "639068b0bd50cb571bd8591e",
"project_simple_name": "xhh_test1",
"relate_state_id": "node_state_0_79697751",
"relate_state_name": "",
"related_state_key": "state_0",
"task_id": 79697511,
"task_name": "123",
"updated_at": 1718864911164,
"updated_by": "7147600751534030867",
"work_item_id": 79697751,
"work_item_name": "hook测试",
"work_item_type": "story"
}
}}
Field Value结构参考
FAQ
webhook 支持获取插件控件里的数据吗？
不支持
