概述

在控制台 AppId 设置页配置 CallbackUrl 后，信封状态发生变更时，服务端将向 CallbackUrl 发送 POST 请求。 > ⚠️ 注意：回调均为 POST 请求。若收到 GET 请求，请确认 CallbackUrl 是否存在 HTTP 到 HTTPS 的 301/302 跳转。

配置步骤

1. 登录控制台，进入「应用管理」→ 选择目标 AppId
2. 在「回调配置」区域填写 CallbackUrl（须为公网可达的 HTTPS 地址）
3. 保存后系统自动生成 32 字符的 CallbackKey（Base62 编码），用于加解密回调数据
4. 妥善保管 CallbackKey，遗失后需重新生成（旧 Key 立即失效）

⚠️CallbackUrl 必须为 HTTPS 协议
CallbackUrl 必须为公网可达地址（不允许内网 IP、localhost）
每个 AppId 可配置多个 CallbackUrl，各自拥有独立的 CallbackKey
不同 CallbackUrl 使用各自独立的 CallbackKey，互不影响

数据格式与加密

{
  "encrypt": "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGU..."
}

加密算法

算法

AES-256-GCM

密钥

32 字节（256 位）

随机数（Nonce）

12 字节（96 位，随机生成）

密文格式

Base64( nonce[12字节] + GCM_ciphertext + GCM_tag[16字节] )

解密流程

1. 从请求 Body 中取出 encrypt 字段值
2. 对该值进行 Base64 标准解码，得到 raw bytes
3. 前 12 字节为 nonce，剩余部分为 GCM ciphertext（含 16 字节 auth tag）
4. 使用 CallbackKey（32 字节，UTF-8 编码）构造 AES-256-GCM 解密器
5. 调用 GCM.Open(nonce, ciphertext) 解密得到原始 JSON 明文
6. 将 JSON 反序列化为 EnvelopeCallbackPayload 对象

投递策略

HTTP 超时

5 秒（HTTP 请求超时）

成功条件

客户端在 5 秒内返回 HTTP 200 状态码

最大重试

重试间隔

1 秒、2 秒、3 秒、4 秒、5 秒 → 10 秒、15 秒、20 秒、25 秒、30 秒、35 秒、40 秒、45 秒、50 秒、55 秒 → 1 分、2 分、3 分、4 分、5 分、6 分、7 分、8 分、9 分、10 分 → 15 分、25 分、35 分、45 分、55 分 → 1 时、2 时、3 时、4 时、5 时、6 时

顺序保证

同一信封 + 同一集成的回调按事件发生时间顺序投递，确保事件顺序一致性

ℹ️重试间隔随次数增加。一旦收到 HTTP 200 响应，平台不再重发该条回调。36 次仍失败则平台视为此消息无法投递并丢弃。

最佳实践

💡

妥善保管 CallbackKey，不要硬编码在客户端代码中，建议使用环境变量或密钥管理服务
回调处理逻辑应尽量轻量，确保在 5 秒内返回 HTTP 200，复杂业务逻辑建议异步处理
建议对回调事件做幂等处理，因为在极端情况下同一事件可能被投递多次
建议记录回调日志，便于排查问题
建议通过 EnvelopeId + EventType + OccurredAt 组合判断事件唯一性

获取合同下载信息信封事件