回调通知配置

接口描述

异步任务（归集、下载、开票、登录等）产生任务通知后，柠檬云会以 POST 方式将通知推送到接入方配置的回调地址，接入方无需持续轮询任务状态。

💡

注意：回调地址暂不支持接口自助修改，需联系技术支持完成绑定。普通应用每个 appId 仅支持绑定一个回调地址。

如何配置

联系柠檬云技术支持，提供以下信息即可完成配置：

需提供的信息	说明
appId	您的应用 ID
回调 URL	接收 `POST` 请求的地址，须外网可达并能在超时时间内返回 2xx 状态码

如需校验回调来源，由柠檬云生成 RSA 密钥对，将加密后的私钥配置到平台，并向接入方提供公钥。接入方无需生成或提交签名私钥。

推送报文

柠檬云以 POST 方式向回调地址发送 JSON 请求。请求体结构如下，taskType 为可选字段，data 的具体内容随任务类型变化：

{
    "taskId": 5151471684213235391,
    "appId": "your-app-id",
    "taskType": 100,
    "taskStatus": 1,
    "timestamp": 1720000000000,
    "data": {}
}

字段	类型	说明
taskId	Integer (int64)	任务 ID，与发起任务时返回的任务标识对应；部分业务接口的历史字段名为 `taskID`
appId	String	发起任务的应用 ID
taskType	Integer	任务类型，部分通知可能不提供
taskStatus	Integer	任务状态；通常 `1` 表示成功、`-1` 表示失败，其他值以具体任务接口约定为准
timestamp	Integer	消息版本时间戳，单位为毫秒
data	Object / null	任务结果或附加数据，字段随任务类型变化

接入方应以 taskId 作为幂等键。同一任务可能因网络异常收到多次通知，不能将重复通知当作不同任务处理。

重试机制

当回调请求超时、网络异常或服务返回非 2xx 状态码时，系统会认为本次通知失败并发起重试。仅返回 2xx 即视为 HTTP 层接收成功，不会校验响应 JSON 中是否包含特定的 code 或 msg 字段。

重试次数由服务配置决定，实际以当前环境配置为准；重试间隔采用带少量随机抖动的指数退避策略，不能依赖固定的秒数或固定的通知次数。达到重试上限后不再继续发送，建议接入方使用 taskId 做幂等处理，并保留主动查询作为降级手段。

失败场景	处理
连接超时、网络错误	按重试策略重新发送
返回非 2xx 状态码	按重试策略重新发送
返回 2xx 状态码	视为接收成功，不再重试

响应要求

回调地址收到请求并完成必要的幂等记录后，应返回 HTTP 2xx 状态码表示接收成功。响应体没有固定 JSON 格式要求，可以为空。

💡

注意：不要在完成业务处理后才等待过长时间再响应。超时或返回非 2xx 都会触发重复推送。

推送请求头

请求头包含 Content-Type: application/json，不应依赖其他非固定请求头进行业务鉴权。

如果平台为该应用启用了回调签名，签名信息会作为 URL 查询参数发送，而不是请求头：

Header	类型	说明
Content-Type	String	`application/json`
其他 Header	String	非固定字段，不保证存在

URL 参数	类型	说明
timestamp	String	签名生成时间戳
nonce	String	随机字符串
signature	String	平台使用私钥生成的 RSA-SHA256 签名，采用 Base64 编码

未启用回调签名时，不会发送 timestamp、nonce、signature 参数。

以下为启用回调签名后，接入方实际接收到的请求结构示例：

查询参数中的 timestamp 用于签名；请求体中的 timestamp 是任务消息时间戳，两者含义不同。

验签时，接入方按以下规则构造待验签字符串：

读取收到的原始 JSON 请求体字节，按 UTF-8 转为字符串并进行 Base64 编码，得到 dataString。不得先解析为对象再重新序列化，否则字段顺序或空白字符变化会导致验签失败。

将 timestamp、nonce、dataString 按字符串升序排列后直接拼接。

使用柠檬云提供的公钥和 RSA-SHA256 算法校验 signature。

接口描述#

如何配置#

推送报文#

重试机制#