Webhook 接口说明文件

1. 简介

Webhook 是一种允许外部系统与我们的应用程序进行实时通信的机制。通过设置 Webhook，您可以在特定事件发生时自动向指定的URL发送HTTP POST 请求。本文档详细说明了业务系统如何配置和使用无纸化签署系统的Webhook 接口。

2. WebHook接口交互流程

业务系统根据本接口设计并实现一个Webhook回调接口，接口方法：POST 接口接收的数据格式：application/json 接收的内容：参考接口定义文件

业务系统将接口地址给无纸化签署系统，由实施人员配置其接口地址

无纸化签署系统中其对应业务系统产生的业务在满足其事件发生时（比如文件签署完成、数据签名签署完成）将对应的信息内容回调至业务系统

业务系统接收到消息，并根据预定义的格式解析数据。

3. 接口 URL

3.1 数据签名回调

以下是一个数据签名完成的回调示例

请求方法：POST

内容格式：applicaiton/json

请求内容：Body（如下所示）

{
  "event": "dataSignatureCompleted",
  "eventDescription": "数据签名完成",
  "target": {
    "destination": "https://webhook.site/5c601c31-1ffa-4750-8872-cb69257d7af5"
  },
  "rawData": "{\"business\":{\"patientId\":\"AA12345678\",\"patientName\":\"李某某\",\"admissionNumber\":null,\"idCard\":null,\"serviceType\":\"D_西药处方\",\"departmentName\":\"ceshike\",\"departmentId\":null,\"doctorName\":\"签名医生\",\"doctorId\":\"lidd\",\"serviceId\":\"L20240512203223\"},\"signature\":{\"signWsid\":\"WSID_SIGN_0000018f6cca445c0242196331aa0001\",\"businessWsid\":\"WSID_BUSI_0000018f6cca420a0242196331aa0001\",\"signingData\":\"这是待签原文\",\"authorWsid\":\"WSID_EUSR_0000018eccb6b8caf889d29c4a420001\",\"signStatus\":\"SIGNED\",\"signValue\":\"MEUCIBZSKnAuf9GLt29xCXvxbxG2C4O4GEy1xuRyp+CZTeapAiEAtcLiiYg80gxhiovIl5JjMwL8FTB3qsqIljGcqgSJmQY=\",\"signDatetime\":1715517253000,\"signStatusReason\":null,\"appendTimestamp\":1},\"appInfo\":{\"appId\":\"1840e3e1b03ba689b193fa5acc2\",\"appName\":\"标准签署应用\"}}",
  "needCallBack": false
}

参数说明

顶层参数

参数名称	参数类型	参数说明
`event`	string	事件类型
`eventDescription`	string	事件描述
`target`	object	目标信息
`rawData`	object	事件的原始数据
`needCallBack`	boolean	是否需要回调

`target` 对象

参数名称	参数类型	参数说明
`destination`	string	目标 URL

`rawData` 对象

参数名称	参数类型	参数说明
`rawData`	string	业务对象JSON字符串信息，为转义后的JSON字符串

rawData字符串经过去除转义后，解析的JSON结构如下所示：

{
    "business":
    {
        "patientId": "A123456",
        "patientName": "张三五",
        "admissionNumber": "0000000",
        "idCard": "510723199601034411",
        "serviceType": "hulijilu",
        "departmentName": "内科",
        "departmentId": "0202",
        "doctorName": "王倩",
        "doctorId": "1461",
        "serviceId": "sjqm-20240413-29-80-1-6",
        "customTag": "sjqm-20240413-29-80-1-6"
    },
    "signature":
    {
        "signWsid": "WSID_SIGN_00000192f62e61712a1d9e8051900001",
        "businessWsid": "WSID_BUSI_00000192f62e616a2a1d9e8051900001",
        "signingData": " 胸部正位片示：两侧胸廓对称、所见骨质未见异常； 两侧肺野透亮度正常， 未见异常密度影； 两肺纹理清晰，无增粗、增多、变形；两肺门无增大、增浓；心影形态、大小在正常范围内；主动脉影未见异常；纵隔居中，气管居中；两膈面光滑，肋膈角锐利。",
        "authorWsid": "WSID_EUSR_0000018b18d88683c27eee096d6d0001",
        "signStatus": "SIGNED",
        "signValue": "MEQCIE20gg2BHmbroBWU0Ho/1oNweD5IgxpowsvTNEzt6vQTAiAEwXDN2itTGZ84gcO1ErISE/XQFmcVtfSCP7WlGB9IBg==",
        "signDatetime": 1730707098000,
        "signStatusReason": null,
        "appendTimestamp": 1,
        "handleMode": "AUTO"
    },
    "appInfo":
    {
        "appId": "125e577b3d9f889d29c4a425ec1",
        "appName": "开放平台事件推送应用"
    }
}

其结构说明如下所示：

顶层字段	子字段	参数类型	参数说明
`business`	`patientId`	string	患者 ID
	`patientName`	string	患者姓名
	`admissionNumber`	string	住院号：（门诊为 null，住院为住院号）
	`idCard`	string	身份证号：（当前为 null）
	`serviceType`	string	服务类型：西药处方
	`departmentName`	string	科室名称：测试科
	`departmentId`	string	科室 ID：（当前为 null）
	`doctorName`	string	医生姓名：签名医生
	`doctorId`	string	医生工号
	`serviceId`	string	业务系统系统的自定义标识符
	`extraParam`	string	扩展参数，业务方传入的自定义扩展参数
`signature`	`signWsid`	string	签署对应的记录唯一标识符WSID
	`businessWsid`	string	业务唯一标识符WSID
	`signingData`	string	待签名的数据
	`authorWsid`	string	作者的用户唯一标识符WSID
	`signStatus`	string	签名状态：已签名（SIGNED）
	`signValue`	string	签名的值
	`signDatetime`	number	签名的日期和时间（时间戳）
	`signStatusReason`	string	签名状态的原因：
	`appendTimestamp`	number	是否追加时间戳：固定为1
	`handleMode`	string	签署模式，NORMAL：显示签署，AUTO：自动签署
	`certificate`	Object	签名证书信息
	`certificate.signCert`	String	base64编码的证书
	`certificate.signCertSerialNumber`	String	证书序列号
	`certificate.notBefore`	number	证书有效期起始时间
	`certificate.notAfter`	number	证书有效期截止时间
	`certificate.issuerName`	String	证书颁发者
	`certificate.subjectName`	String	证书持有者
	`certificate.publicKey`	String	base64编码格式的公钥
`appInfo`	`appId`	string	应用程序的 ID
	`appName`	string	应用程序的名称：标净签署应用

以上表格详细展示了 JSON 数据中的所有关键字段和参数，提供了一个清晰的视图来理解和使用这些信息。如果需要进一步的调整或有其他特定要求，请告诉我！

3.2 文件签名回调

以下是一个文件签名的回调示例

请求方法：POST

内容格式：applicaiton/json

请求内容：Body（如下所示）

{
	"event": "envelopeCompleted",
	"eventDescription": "信封流程完成",
	"target": {
		"destination": "http://172.21.1.15:8086/CASignInfo"
	},
	"rawData": "{\"business\":{\"patientId\":\"352401111076\",\"patientName\":\"赵彬\",\"admissionNumber\":\"A02502194\",\"idCard\":\"510823199807048945\",\"serviceType\":null,\"departmentName\":\"超声医学科\",\"departmentId\":\"1\",\"doctorName\":\"张玉麒\",\"doctorId\":\"3290\",\"serviceId\":\"61127617990786155\"},\"envelope\":{\"title\":\"chaoshengjianchabaogao\",\"envelopeWsid\":\"WSID_ENVE_0000018cf72a81abd28bfda326d70001\",\"status\":\"ED_SUCCESS\",\"statusDescription\":\"成功处理完成\",\"sendDatetime\":\"24-1-11 下午2:16\",\"finishedDatetime\":\"24-1-11 下午2:17\",\"files\":[{\"md5\":\"84b468fa5e83f46af3bf96e4d14d64a9\",\"name\":\"202401111416461613001737334001.pdf\",\"url\":\"https://hospital-api.signit.cn/v1/file/files/WSID_FILE_0000018cf72af5c85e4da8789e4922a5?token=05fb2749a93048c70d9f3e539863b8a4&salt=udQ56m8NckK1sw5041&open=true&ts=1704953855895&ets=3D08A5D9E6B7D551AE23C6EE0F8B8C27DFF69D416A8E7655\",\"wsid\":\"WSID_FILE_0000018cf72af5c85e4da8789e4922a5\",\"byteSize\":\"729925\"}]},\"appInfo\":{\"appId\":\"1854e7ba96f02420a0a0a171710\",\"appName\":\"自定义应用\"},\"customTag\":\"61127617990786155\",\"invokeNo\":\"202401111416461613001737334001_WSID_ENVE_0000018cf72a81abd28bfda326d70001\",\"returnUrl\":null,\"actions\":null}",
	"needCallBack": false
}

参数说明

顶层参数

参数名称	参数类型	参数说明
`event`	string	事件类型
`eventDescription`	string	事件描述
`target`	object	目标信息
`rawData`	object	事件的原始数据
`needCallBack`	boolean	是否需要回调

`target` 对象

参数名称	参数类型	参数说明
`destination`	string	目标 URL

`rawData` 对象

参数名称	参数类型	参数说明
`rawData`	string	业务对象JSON字符串信息，为转义后的JSON字符串

rawData字符串经过去除转义后，解析的JSON结构如下所示：

{
    "business":
    {
        "patientId": "A1122334455",
        "patientName": "王二发",
        "admissionNumber": "8777202101171970",
        "idCard": "513030199911113210",
        "serviceType": "mazuidan",
        "departmentName": "骨科",
        "departmentId": "0095",
        "doctorName": "多多益善",
        "doctorId": "lidd",
        "serviceId": "3C3E244e-ECBD-c38a-DEb6-fe97D2F0c1F7"
    },
    "envelope":
    {
        "title": "麻醉单",
        "envelopeWsid": "WSID_ENVE_000001930574f619f889d29c4a420001",
        "status": "ED_SUCCESS",
        "statusDescription": "成功处理完成",
        "sendDatetime": "1730963373000",
        "finishedDatetime": "1730963376000",
        "files":
        [
            {
                "md5": "045b768f7dd879049c6df228b6f52210",
                "name": "202411071509302732485807635001.pdf",
                "url": "http://10.10.9.249:6153/v1/file/files/WSID_FILE_00000193057504a02a1d9e8051907b10?token=559d0ff18dcce4dd59bfe74adc6c2699&salt=kIAdjQeKaT56p8DL8b&open=true&ts=1730963376980&ets=528F7E1D8C88B98689D7CC8A5BEF6B2F2798D958CF6E560F",
                "wsid": "WSID_FILE_00000193057504a02a1d9e8051907b10",
                "byteSize": "109835"
            }
        ],
        "participants":
        [
            {
                "wsid": "WSID_EPAR_000001930574f6a2f889d29c4a420001",
                "signerType": "DOCTOR",
                "handMode": "AUTO",
                "name": "多多益善",
                "idCard": "110101198402150452",
                "phone": "18896325130",
                "hospitalUserJobId": "lidd",
                "hospitalUserDepartmentName": "手机盾测试科"
            }
        ]
    },
    "appInfo":
    {
        "appId": "125e577b3d9f889d29c4a425ec1",
        "appName": "开放平台事件推送应用"
    },
    "customTag": "3C3E244e-ECBD-c38a-DEb6-fe97D2F0c1F7",
    "invokeNo": "WSID_ENVE_000001930574f619f889d29c4a420001",
    "returnUrl": null,
    "actions": null
}

其顶层结构说明如下所示：

综合数据结构表

此表格综合展示了 JSON 数据的顶层字段和对应的子对象参数，提供了一个全面的视角来理解整个数据结构。

顶层字段	子字段	参数类型	参数说明
`business`	`patientId`	string	患者 ID
	`patientName`	string	患者姓名
	`admissionNumber`	string	住院号：（门诊为 null，住院为住院号）
	`idCard`	string	患者身份证号
	`serviceType`	string	签名的业务类型（当前为 null）
	`departmentName`	string	科室名称
	`departmentId`	string	科室 ID（当前为 null）
	`doctorName`	string	医生姓名
	`doctorId`	string	医生工号
	`serviceId`	string	服务 ID
	`extraParam`	string	扩展参数，业务方传入的自定义扩展参数
`envelope`	`title`	string	信封标题
	`envelopeWsid`	string	信封的工作区ID
	`status`	string	信封状态：ED_SUCCESS为完成状态
	`statusDescription`	string	状态描述
	`sendDatetime`	string	发送时间
	`finishedDatetime`	string	完成时间
	`files`	array	包含文件的数组
	`file.md5`	string	文件的MD5
	`file.name`	string	文件的文件名称
	`file.url`	string	文件的下载地址：默认为公网互联网地址，内网下载需要将 https://hospital-api.signit.cn 替换为内网地址：http://172.21.1.113:6153
	`file.wsid`	string	文件的唯一编号
	`file.byteSize`	string	文件的大小
	`participants`	array	签署方信息
	`participant.wsid`	string	签署方唯一标识
	`participant.signerType`	string	签署方类型，DOCTOR：医护，PATIENT：患者
	`participant.handMode`	string	签署模式，NORMAL：显示签署，AUTO：自动签署
	`participant.name`	string	签署方姓名
	`participant.idCard`	string	证件号
	`participant.phone`	string	联系电话
	`participant.hospitalUserJobId`	string	医护人员工号（患者没有值）
	`participant.hospitalUserDepartmentName`	string	医护所属科室（患者没有值）
`appInfo`	`appId`	string	应用程序的ID
	`appName`	string	应用程序的名称
`customTag`		string	自定义标签
`invokeNo`		string	一个唯一的调用编号
`returnUrl`		string	回调URL（如果有的话）
`actions`		object	包含可执行操作的详绀信息（当前为 null）

WebHook回调接口文档说明

Webhook 接口说明文件#

1. 简介#

2. WebHook接口交互流程#

3. 接口 URL#

3.1 数据签名回调#

参数说明#

顶层参数#

target 对象#

rawData 对象#

3.2 文件签名回调#

参数说明#

顶层参数#

target 对象#

rawData 对象#

综合数据结构表#

Webhook 接口说明文件

1. 简介

2. WebHook接口交互流程

3. 接口 URL

3.1 数据签名回调

参数说明

顶层参数

`target` 对象

`rawData` 对象

3.2 文件签名回调

参数说明

顶层参数

`target` 对象

`rawData` 对象

综合数据结构表