飞书项目帮助中心

Appearance

Return to top
页面导航

Webhook 使用

自动化中，在触发器下方添加 Webhook 操作并触发时，会推送整合后的新版Webhook 格式。

从以前事件与通知系统自动迁移至自动化的配置，会兼容老版 Webhook 格式，但请尽快升级。如果删除了旧配置后重新配置 Webhook，兼容格式不再推送，只推送新版格式。

配置方式

如何配置 Webhook？

在流程图中添加 Webhook 操作即可配置 Webhook。触发时，会推送整合后的新版 Webhook 格式。

对应关系

触发器
老版 webhook 事件
老版 webhook 对应 eventType
event_type
创建工作项
需求创建
StoryCreated

WorkitemCreateEvent

工作项创建
EventCreate-{工作项类型}
字段值修改
需求修改
StoryValueChanged
WorkitemUpdateEvent
工作项修改
EventUpdate-{工作项类型}
终止工作项
需求终止
StoryAborted
WorkitemAbortedEvent（工作项终止）
WorkitemRestoreEvent（工作项恢复）

工作项终止
EventAborted-{工作项类型}
需求状态修改
需求状态修改
StoryStageChanged
WorkitemStatusEvent

工作项状态修改
工作项状态更新
EventUpdateStatus-{工作项类型}
任务状态修改
任务状态修改
EventUpdateStatus-task
TaskStatusEvent
任务修改
任务修改

EventUpdate-task
TaskUpdateEvent
角色操作

需求人员分配
StoryRoleAssigned
WorkitemPersonAssignedEvent

工作项人员分配
EventRoleAssigned-{工作项类型}
节点负责人分配(需求)
WFNodeOwnerChanged
节点负责人分配(其他工作项)
WFNodeOwnerChanged-{工作项类型}
节点状态修改
节点完成(需求)
节点完成(其他工作项)
WFNodeChecked
WFNodeChecked-{工作项类型}
WorkFlowNodeStatusEvent

节点到达(需求)
节点完成(其他工作项)
WFNodeReached
WFNodeReached-{工作项类型}
节点回滚(需求)
节点完成(其他工作项)
WFNodeRollbacked
WFNodeRollbacked-{工作项类型}
节点排期操作
节点排期变更(需求)
WFNodeScheduleChanged
WorkFlowNodeScheduleEvent
节点排期变更(其他工作项)
WFNodeScheduleChanged-{工作项类型}
评论操作
需求评论操作
StoryCommentAdded
WorkitemCommentEvent
工作项评论操作
EventCommentAdded-{工作项类型}
工作项归档
需求归档
StoryFinished
WorkitemFinishEvent
工作项归档
EventFinished-{工作项类型}
删除工作项
需求删除
StoryDeleted
WorkitemDeleteEvent

工作项删除
EventDelete-{工作项类型}
定时循环


TimedTriggerEvent
动态时间任务


DynamicTimeTriggerEvent

新版webhook对应Body格式

  1. webhook 设计有幂等串，header -> uuid，可以考虑使用幂等串去重
  2. webhook 推送后 6s 超时，超时会重试，最大重试次数 3 次
  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
            "add_owners": [],          // 新增的负责人
            "delete_owners": [],    // 删除的负责人
        }]
    }
}

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，冗余
            "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_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位
        "task_id":int, //任务对应的id，64位
        "project_key": "",   // string，空间ID
        "project_simple_name": "", // string，空间域名
        "updated_at": 1639548775000, // int，64位，更新时间戳
        "updated_by": "",    // string，更新人的userkey
        "pre_status": int,
        "cur_status": int,
    } 
}

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位
        "task_id":int, //任务对应的id，64位
        "project_key": "",   // string，空间ID
        "project_simple_name": "", // string，空间域名
        "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{}
            },
        ]
    }
}

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_schedule":{  // 节点总排期
                        "estimate_start_date": 1111,
                        "estimate_end_date": 1111,
                        "points": 111
                    },
                    "owner_schedules":[{    //  差异化排期的人员排期
                        "owner": "",
                        "estimate_start_date": 1111,
                        "estimate_end_date": 1111,
                        "points": 111
                    }]
                }]
            },
        ]
    }
}

Field Value结构参考

开放能力-字段&属性解析格式