Webhook自定义模板概述

服务类型

服务是指第三方应用服务，通常以HTTP Server为主。目前LigaAI主要支持的服务类型有：LigaAI服务、企业微信、钉钉、飞书。

在使用场景上，企业微信、钉钉、飞书主要为IM机器人消息通知，LigaAI服务则适用于用户的个性化定制开发。

事件类型

事件是指由系统自身或者用户操作触发而产生的事件信息。事件将包括相关的业务数据以及事件的基础信息。目前LigaAI支持事件有：

• 工作模块
• 创建工作
• 更新工作
• 删除工作
• 评论模块
• 发布评论
• 更新评论
• 删除评论
• 附件模块
• 上传附件
• 删除附件
• 子任务模块
• 新增子任务
• 更新子任务
• 删除子任务
• 关联关系模块
• 添加关联关系
• 删除关联关系

不同的事件类型，其事件的数据内容是有差别的，具体数据结构内容参考：事件类型对应的数据模块

自定义模板

Webhook支持用户使用模板自定义发送内容，主要支持Markdown文本、自定义JSON两种方式，支持通过自定义变量的方式读取事件消息的内容来填充模板。

变量语法

通过JsonPath的语法来访问事件的数据，并在此基础上支持了模板函数，具体使用如下：

变量描述：

${issue.startDate}

函数描述：

${issue.startDate|date:yyyy-MM-dd HH:mm}

支持函数：

1、日期格式化函数

函数名：date
参数：时间格式化字符串，参考（org.apache.commons.lang3.time.DateFormatUtils）
示例：${startDate|date:yyyy-MM-dd HH:mm}
（默认时区为系统设置-时间设置-组织时区中设定的组织统一时区）

• 对日期数据设定格式化函数
• 在飞书端（或企业微信、钉钉）接收到的内容为格式化后的文本。
• 自定义模板配置内容如下，日期格式化函数为 ${issue.dueDate|date:yyyy-MM-dd HH:mm}：

## ${event.type.action.name}${event.type.subject.name} 
${issue.type.name} | ${issue.summary} 
${field.issue.status.name}：${issue.status.name} 
${field.issue.assignee.name}：${issue.assignee.name} 
${field.issue.priority.name}：${issue.priority.name} 
${field.issue.dueDate}：${issue.dueDate|date:yyyy-MM-dd HH:mm} 
${field.issue.description}：${issue.description} 
操作人：${trigger.user.name} 
[查看详情](${issue.url|blank}) 

• 你将接收到日期内容形如年-月-日 时:分。飞书端接收效果截图如图：

• 不使用日期格式化函数时
• 一般为LigaAI服务场景，目前暂未开放LigaAI服务的自定义模板，我们将向你配置的接收服务器发送日期的毫秒级时间戳。
• 自定义模板配置内容如下，未使用日期格式化函数${issue.dueDate}：

{ 
"工作流状态": ${issue.status.name}, 
"工作优先级": ${issue.priority.name}, 
"工作截止时间": ${issue.dueDate}, 
"工作描述": ${issue.description} 
} 

• 我们将向你的接收服务器发送日期内容形如1676628000000：

{
 "工作流状态": "未开始", 
"工作优先级": "中等", 
"工作截止时间": 1676628000000, 
"工作描述": 
"目前LigaAI主要支持的服务类型有：LigaAI服务、企业微信、钉钉、飞书。"
 }

2、属性为空或者不存在时清理

函数字符：blank
参数：无
说明：当事件的数据对象不包含变量属性或者该变量属性的值为null时，会自动删除该属性所在的一行。
示例：${issue.url|blank}

• 对于已删除的工作
• 我们不提供工作的访问链接，使用清理函数后，你将不会收到意外的数据内容。
• 自定义模板内容如下，对工作的访问链接使用了清理函数${issue.url|blank}：

## ${event.type.action.name}${event.type.subject.name} 
${issue.type.name} | ${issue.summary} 
${field.issue.status.name}：${issue.status.name} 
${field.issue.assignee.name}：${issue.assignee.name} 
${field.issue.priority.name}：${issue.priority.name} 
${field.issue.dueDate}：${issue.dueDate|date:yyyy-MM-dd HH:mm} 
${field.issue.description}：${issue.description} 
操作人：${trigger.user.name} 
[查看详情](${issue.url|blank})

• 在创建工作事件（非删除事件）中
• 我们提供了工作的访问链接，你在飞书端的接收效果截图如图，“查看详情”的文本行将正常显示：

• 在删除工作事件中
• 我们不提供工作的访问链接，你在飞书端的接收效果截图如图，“查看详情”的文本行不再显示：

使用示例

飞书markdown自定义模板

企微&钉钉类似，区别在于各家IM平台对于Markdown语法的支持

LigaAI系统配置截图：

自定义模板内容：

${event.type.subject.name}${issue.type.name} 
${issue.summary} 
状态：${issue.status.name} 
执行人：${issue.assignee.name} 
优先级：${issue.priority.name} 
${field.issue.estimatePoint.value}：${issue.estimatePoint.value} 
${field.issue.createBy.name}：${issue.createBy.name} 
截止时间：${issue.dueDate|date:yyyy-MM-dd HH:mm:ss} 
描述：${issue.description} 
操作人：${trigger.user.name} 
[查看详情](${issue.url|blank}) 

飞书客户端接收效果：

LigaAI自定义JSON模板：

目前系统暂未开放LigaAI格式的自定义模板配置选项。所有消息将按以下模板发送：

{
    "type": ${event.type.id},
    "date": ${trigger.date},
    "tenant": ${tenant},
    "trigger": ${trigger},
    "data": {
        "issue": ${issue},
        "comment": ${comment},
        "attachment": ${attachment},
        "subtask": ${subtask},
        "relationIssue":${relationIssue}
    }
}

请求数据示例如下：

{
    "date": 1676627206432,
    "data": {
        "issue": {
            "summary": "Webhook自定义LigaAI服务消息",
            "dueDate": 1676628000000,
            "description": "目前LigaAI主要支持的服务类型有：LigaAI服务、企业微信、钉钉、飞书。",
            "project": {
                "name": "示例项目",
                "description": "点击查看示例项目，体验 LigaAI 的亮点功能",
                "id": 900
            },
            "updateTime": 1676627206432,
            "priority": {
                "optionKey": "Medium",
                "name": "中等",
                "id": 1200
            },
            "type": {
                "code": "story",
                "name": "故事",
                "id": 1100
            },
            "url": "https://ligai.cn/app/work",
            "number": 8,
            "createBy": {
                "phone": "12345678901",
                "name": "张三",
                "id": 101,
                "email": "zhangsan@zhikan.net.cn"
            },
             "follows": [ 
                { 
                  "id": 101, 
                  "name": "张三", 
                  "phone": "13812345678", 
                  "email": "zhangsan@zhikan.net.cn" 
                 }, 
                 { "id": 102, 
                   "name": "李四", 
                   "phone": "13812345679", 
                   "email": "lisi@zhikan.net.cn" 
                  } 
             ],
            "estimatePoint": {
                "autoCalculateFlag": 0,
                "value": 8
            },
            "createTime": 1676627206432,
            "updateBy": {
                "phone": "12345678901",
                "name": "张三",
                "id": 101,
                "email": "zhangsan@zhikan.net.cn"
            },
            
            "id": 100,
            "startDate": 1676595600000,
            "status": {
                "code": "story-todo",
                "name": "未开始",
                "id": 4,
                "category": {
                    "name": "Todo",
                    "id": 4
                }
            }
        }
    },
    "trigger": {
        "date": 1676627206432,
        "user": {
            "phone": "12345678901",
            "name": "张三",
            "id": 101,
            "email": "zhangsan@zhikan.net.cn"
        }
    },
    "type": "Issue.Create",
    "tenant": {
        "id": 1
    }
}

LigaAI服务说明

• 请求方式：POST
• 请求头：

• 请求体数据格式：application/json; charset=utf-8，默认数据格式示例：

{
    "date": 1675329348640,
    "data": {
        "issue": {
            "owner": {
                "name": "张三",
                "id": 101,
                "email": "zhangsan@zhikan.net.cn"
            },
            "summary": "Webhook自定义LigaAI服务消息",
            "dueDate": 1675332000000,
            "sprint": {
                "name": "【示例】迭代的名称",
                "id": 1400
            },
            "description": "目前LigaAI主要支持的服务类型有：LigaAI服务、企业微信、钉钉、飞书。",
            "project": {
                "name": "示例项目",
                "description": "点击查看示例项目，体验 LigaAI 的亮点功能",
                "id": 900
            },
            "updateTime": 1675329348640,
            "priority": {
                "optionKey": "Highest",
                "name": "最高",
                "id": 1200
            },
            "type": {
                "code": "story",
                "name": "故事",
                "id": 1100
            },
            "url": "https://ligai.cn/app/work",
            "number": 21,
            "createBy": {
                "name": "张三",
                "id": 101,
                "email": "zhangsan@zhikan.net.cn"
            },
            "estimatePoint": {
                "autoCalculateFlag": 0,
                "value": 13
            },
            "createTime": 1675325728466,
            "updateBy": {
                "name": "张三",
                "id": 101,
                "email": "zhangsan@zhikan.net.cn"
            },
            "assignee": {
                "name": "张三",
                "id": 101,
                "email": "zhangsan@zhikan.net.cn"
            },
            "follows": [{
					"id": 101,
					"name": "张三",
					"phone": "13812345678",
					"email": "zhangsan@zhikan.net.cn"
				},
				{
					"id": 102,
					"name": "李四",
					"phone": "13812345679", 
					"email": "lisi@zhikan.net.cn"
				}
			],
            "id": 100,
            "startDate": 1675213200000,
            "status": {
                "code": "scrum-development",
                "name": "开发",
                "id": 4,
                "category": {
                    "name": "In Progress",
                    "id": 3
                }
            }
        }
    },
  "customFields": [
		{
			"customFieldName": "缺陷原因",
			"fieldCode": "customfield_50776203",
			"fieldValue": [
				{
					"name": "代码错误",
					"value": 50776207
				}
			]
		}
	],
  "relationIssue": {
		"destineIssues": [
				{
					"destinationProjectId": 225724408,
					"destinationIssueId": 276042168,
					"relationshipType": "CAUSES"
				}
			],
			"fromIssue": {
				"actionType": "delete",
				"fromIssueId": 276135673
			}
	},
   "trigger": {
        "date": 1675329348640,
        "user": {
            "name": "张三",
            "id": 101,
            "email": "zhangsan@zhikan.net.cn"
        }
    },
    "type": "Issue.Update",
    "tenant": {
        "id": 1
    }
}

• 接收webhook后响应要求：

   应用收到HTTP POST请求后，需要在3秒内以HTTP 200状态码以及如下JSON响应体响应该请求。否则认为本次推送失败，在WebHooks-对应Webhook的发送记录中，该请求将按失败请求记录。

{
 "errcode": 0
 }

• 超时说明：

连接超时3秒，请求超时3秒，共6秒。

附录1：模板变量