状态回调

接口说明

回调地址与回调密钥在开通时配置，创建合同的请求中不传递。合同创建成功本身不产生回调。

出现以下变化时，平台向回调地址发送请求：

• 任一签署方进度变化
• 合同状态变化，包括完成、撤回、拒签、作废、过期

同一次业务变化只推送一条回调。报文包含事件发生后的合同状态，以及全部签署方的当前进度。接入方按报文覆盖本地状态。

请求地址：开通时配置的 HTTPS 回调地址

请求方式：POST

Content-Type：application/json

请求参数

报文正文：

参数名称	数据类型	必须	说明
eventId	string	是	事件 ID。同一次事件的重试保持不变
event	string	是	固定 contract.status_changed
occurredAt	string	是	事件时间
contractId	string	是	合同 ID
status	string	是	合同状态
signers	array	是	全部签署方的当前进度
type	string	是	person 或 company
mobile	string	否	个人手机号。企业签署方不返回
creditCode	string	否	统一社会信用代码。个人签署方不返回
needSeal	boolean	是	是否须盖章
status	string	是	waiting / approving / pending / signed / refused

请求头：

参数名称	数据类型	必须	说明
X-Timestamp	string	是	毫秒时间戳
X-Signature	string	是	十六进制小写签名

签名字符串为 {X-Timestamp}.{原始请求体}，使用回调密钥做 HMAC-SHA256。请对原始报文体计算，不要先解析再序列化。

X-Signature = hex(HMAC_SHA256(回调密钥, X-Timestamp + "." + rawBody))

响应参数

接入方校验签名与时间戳后处理业务，并以 HTTP 2xx 应答。建议允许的时钟偏差为 5 分钟，并以 eventId 去重。

未在超时时间内收到 2xx 时，平台按 1 分钟、5 分钟、30 分钟、2 小时重试，此后不再发送该事件。

请求示例

{
  "eventId": "evt_30001",
  "event": "contract.status_changed",
  "occurredAt": "2026-10-27 15:20:00",
  "contractId": "ct_20001",
  "status": "completed",
  "signers": [
    {
      "type": "company",
      "creditCode": "91310000MA1EXAMPLE",
      "needSeal": true,
      "status": "signed"
    },
    {
      "type": "person",
      "mobile": "13900000002",
      "needSeal": true,
      "status": "signed"
    }
  ]
}