接收并处理回调

当订阅的回调操作发生时，开放平台服务器会向回调请求地址发送 HTTP POST 请求，应用方服务器需要接收并处理回调，并立即返回响应内容。 本文将介绍接收并处理回调时涉及的操作。

流程概述

回调订阅整体可分为 4 个步骤： 1、在开发者后台-事件与回调-回调配置配置用于接收事件消息推送的地址（URL）。 2、在开发者后台-事件与回调-回调配置选择需要订阅的回调。 3、在开发者后台-事件与回调-加密配置设置安全校验。用于确认业务服务器接收到的请求来自开放平台，而不是伪造的风险请求。 4、事件触发并推送至应用的回调订阅地址，应用解密消息体并响应成功。

当开放平台服务器推送回调至请求地址后，应用服务器需要接收回调请求，并在 3 秒内完成业务处理、返回响应结果。在该过程中，你需要根据实际配置情况，完成以下操作。

📌 请注意：回调是同步操作，不提供补推机制。如果你的业务服务器超时未响应，则系统会判断回调失败，并在用户前端内展示报错信息。

1. 设置回调地址并响应challenge

配置回调地址后，WPS 开放平台服务器会向该地址发送一个 application/json 格式的 HTTP POST 请求，以验证配置地址的有效。 该 POST 请求中会携带一个 challenge 字段，应用需要在 1 秒内，将接收到的 challenge 值原样返回给 WPS 开放平台。仅回调地址验证通过情况下，才可在后续触发时向请求地址发送回调数据。

请求说明

请求地址	应用方设置的回调地址
请求方法	POST
签名方式	KSO-1

请求头（Header）

Header 名称	参数类型	是否必填	说明
Content-Type	string	是	使用：application/json
X-Kso-Date	string	是	RFC1123 格式的日期，例: Wed, 23 Jan 2013 06:43:08 GMT
X-Kso-Authorization	string	是	KSO-1 签名值，详见：签名方法 注意：此处使用 app_id 作为 access_key，encrypt_key 作为 secret_key

请求体（Body）

名称	参数类型	是否必填	说明
challenge	string	是	应用需要在响应中原样返回的值

请求地址示例

[POST] 应用方设置的回调地址

请求体示例

{
  "challenge": "string"
}

响应体

名称	参数类型	说明
challenge	string	应用在响应中原样返回的值

响应体示例

{
  "challenge": "string"
}

2. 接收回调并做安全校验

当你的业务服务器接收到来自开放平台推送的回调时，你可以通过签名校验的方式确保请求来自开放平台。 如果你已配置了 encrypt_key，则业务服务器接收到回调请求后，可直接使用 app_id 作为 access_key，encrypt_key 作为 secret_key 完成签名校验。

签名示例参考：KSO-1 签名算法说明

3. 接收回调并响应回调

你的业务服务器接收回调请求后，需要在 3 秒内响应回调，以完成客户端（前端）的交互行为。 目前需要订阅回调的功能以及对应的回调结构、使用方式等说明，请参见下表：

功能	callback_name	回调结构
WPS协作消息卡片	xz_card	如果你构建的卡片可通过交互组件完成业务处理，则需要订阅 WPS协作消息卡片 回调。 该回调对应的回调参数、响应参数说明，可参见WPS协作消息卡片回传交互

请求说明

请求地址	应用方设置的回调地址
请求方法	POST
签名方式	KSO-1

请求头（Header）

Header 名称	参数类型	是否必填	说明
Content-Type	string	是	使用：application/json
X-Kso-Date	string	是	RFC1123 格式的日期，例: Wed, 23 Jan 2013 06:43:08 GMT
X-Kso-Authorization	string	是	KSO-1 签名值，详见：签名方法 注意：此处使用 app_id 作为 access_key，encrypt_key 作为 secret_key

请求体（Body）

名称	参数类型	是否必填	说明
callback_name	string	是	回调名称
app_id	string	是	应用id
data	object	是	回调的数据，根据 callback_name 不同有所不同

请求地址示例

[POST] 应用方设置的回调地址

请求体示例

{
  "callback_name": "string",
  "app_id": "string",
  "data": {
    // 回调的数据，根据 callback_name 不同有所不同
  }
}

响应体

名称	参数类型	说明
code	integer	响应代码。非 0 表示失败，参照《状态码说明》
msg	string	响应信息

响应体示例

{
  "msg": "string",
  "code": 0
}