API 回调

CertCloud 通过回调通知客户端订单、证书、预审核组织、预审核域名、审核链接等业务事件。配置回调 URL 与鉴权密钥后，相关事件触发时系统会向该 URL 发起 HTTP POST 请求。可以通过账户回调配置 API查询、更新和测试配置。

回调地址要求

使用 HTTPS 协议，且域名不能解析到内网 IP。
回调 URL 与鉴权密钥长度均不超过 256 个字符。
请求头 X-CC-Callback-Auth 的值为账户设置中的鉴权密钥，接收方应校验该值。
请求头 Content-Type 为 application/json。
响应 HTTP 状态码为 200 表示回调成功，系统不再继续投递。
其他状态码或网络错误均视为失败，系统会按重试策略继续投递。

请求字段

回调请求体为 JSON。不同事件只携带与该事件相关的字段，未携带的字段会省略。

参数	类型	必填	说明
`action_type`	string	是	回调通知类型。常见值：`order` / `cert` / `org` / `domain` / `link` / `esign` / `acme`
`action_id`	string	是	回调通知具体事件 ID，见下方事件列表
`message`	string	是	事件说明文本，语言按账户回调设置生成
`order_id`	string	按需	订单 ID，订单/证书相关事件可能携带
`cert_id`	string	按需	证书 ID，订单签发、重颁发、证书到期、证书吊销等事件可能携带
`org_id`	string	按需	组织 ID，组织或域名预审核事件可能携带
`domain_id`	string	按需	域名 ID，域名预审核事件可能携带
`link_id`	string	按需	审核链接 ID，仅审核链接事件携带
`sub_stage`	string	按需	审核链接进度子阶段，仅 `link:progress` 携带；当前值见“审核链接事件”
`renew_order_id`	string	按需	新续费订单 ID，仅 `order:renewaled` 可能携带
`renew_cert_id`	string	按需	新续费证书 ID，仅 `order:renewaled` 可能携带
`order_status`	string	按需	当前订单状态，订单/证书相关事件可能携带
`acme_client`	object	按需	ACME 客户端信息，仅 ACME 事件携带，结构见"ACME 事件"
`acme_cert`	object	按需	ACME 证书信息，仅 ACME 证书事件携带，结构见"ACME 事件"

事件列表

订单事件 (`action_type = order`)

action_id	含义	说明
`order:submit_ca`	订单提交 CA	订单已提交至 CA 处理
`order:wait_confirm`	订单待确认	订单进入待确认状态
`order:confirmed`	订单已确认	订单后台确认完成
`order:dcv_auth`	订单域名验证值生成	DCV 验证值已生成或更新
`order:domain_verifing`	订单域名验证中	历史事件 ID 保持服务端拼写，注意是 `verifing`
`order:uploaded_confirm`	已上传信息确认函	信息确认函已上传
`order:issuing`	订单签发中	CA 正在签发证书
`order:issued`	订单已签发	通常携带 `cert_id`，可用于获取证书详情
`order:ressiue_confirmed`	重颁发订单已确认	重颁发操作已在后台确认
`order:reissued`	订单重颁发完成	通常携带重颁发后的 `cert_id`
`order:cert_renew`	多年期证书续期提醒	证书即将到期，可在订阅期内发起证书续期
`order:cert_renew_confirmed`	多年期证书续期已确认	续期确认完成
`order:renewaled`	订单已续费	当前订单被新订单续费；通常携带 `renew_order_id` / `renew_cert_id`
`order:revoke_confirmed`	证书吊销已确认	通过吊销域名验证或人工确认吊销完成
`order:revoke_recalled`	证书吊销已撤回	吊销申请撤回
`order:cancel_wait_confirm`	订单取消待确认	取消申请已发起，等待客户经理确认
`order:cancel_confirmed`	订单取消已确认	取消订单后台确认完成
`order:cancel_recalled`	订单取消已撤回	取消申请被撤回
`order:canceled`	订单已取消	订单取消成功
`order:force_canceled`	订单强制取消成功	后台或系统强制取消订单成功
`order:exist_brand_risk`	订单存在品牌高风险	品牌高风险检查命中
`order:risky_domain`	订单存在高风险域名	域名高风险检查命中
`order:caa_failed`	订单 CAA 检查失败	域名 CAA 记录不满足签发要求
`order:dns_sec_validation_error`	订单 DNSSEC 验证失败	订单域名的 DNSSEC 验证失败；修复 DNSSEC 配置后需要重新提交订单。
`order:failed`	订单失败/被 CA 拒绝	`message` 通常包含失败原因
`order:reissue_failed`	订单重颁发失败	重颁发流程失败

证书事件 (`action_type = cert`)

action_id	含义	说明
`cert:expired`	证书已过期	证书已过期
`cert:expired_30`	证书 30 天内到期	证书有效期不足 30 天
`cert:expired_60`	证书 60 天内到期	证书有效期不足 60 天
`cert:expired_90`	证书 90 天内到期	证书有效期不足 90 天
`cert:revoke_wait_confirm`	证书吊销待确认	吊销流程等待人工确认
`cert:revoke_wait_dcv_auth`	证书吊销待 DCV 验证	吊销流程等待域名验证
`cert:revoked`	证书已吊销	证书吊销成功

域名预审核事件 (`action_type = domain`)

action_id	含义	说明
`domain:pending`	域名验证值待配置	验证值失效或重新生成，需要重新配置验证值
`domain:completed`	域名预审核完成	域名验证通过
`domain:expiring`	域名预审核即将到期	距验证有效期失效约 30 天，状态进入待重新验证
`domain:expired`	域名预审核已过期	域名验证有效期已过
`domain:invalid`	域名预审核失效	超过验证窗口仍未完成验证，状态变为失效

组织预审核事件 (`action_type = org`)

action_id	含义	说明
`org:submitted`	组织已提交 CA	组织信息已提交 CA 审核
`org:changed`	组织信息调整	未提交 CA 前，审核人员调整组织信息后触发；接收方应重新拉取组织信息
`org:completed`	组织预审核完成	组织审核通过
`org:expiring`	组织预审核即将到期	距组织验证失效约 30 天，状态进入待重新验证
`org:expired`	组织信息已过期	组织审核有效期已过
`org:public_phone_verified`	公开电话验证完成	仅 SSL OV/EV 旧流程使用
`org:public_email_verified`	公开邮箱验证完成	仅 SSL OV/EV 旧流程使用
`org:legal_representative_verified`	企业法人审核完成	身份认证证书审核链接流程使用
`org:bank_transfer_verified`	对公打款认证完成	身份认证证书审核链接流程使用，仅对公打款成功时触发
`org:invalid`	组织预审核失效	超过验证窗口仍未完成验证，状态变为失效

审核链接事件 (`action_type = link`)

审核链接事件只携带审核链接语义字段，不会混入 order_id、cert_id、org_id、domain_id 等轨道字段。

action_id	含义	说明
`link:submitted`	审核链接已提交 CA	携带 `link_id`，`status` 为 `auditing`
`link:progress`	审核链接进度变更	携带 `link_id` 与 `sub_stage`，不携带 `status`
`link:passed`	审核链接整体通过	携带 `link_id`，`status` 为 `passed`
`link:expired`	审核链接已过期	携带 `link_id`，`status` 为 `expired`
`link:retried`	审核链接失败后重试	已发出的 `link:failed` 视为前次终态；接收方应以新的后续事件为准
`link:failed`	审核链接整体失败	携带 `link_id`，`status` 为 `failed`

link:progress 的 sub_stage 当前可能值：

sub_stage	含义
`meeting_booked`	面审预约成功
`qr_ready`	二维码已生成

meeting_booked 在终端用户通过 CertCloud 审核页面成功预约面审后触发。CA 将验证方式切换为面对面审核，或下发验证入口、会议号、入会地址，不会单独触发此事件；接收方不能据此推断已预约成功。

个人事件 (`action_type = person`)

action_id	含义	说明
`person:meeting_booked`	个人面审预约成功	当前审核链接流程实际通过 `link:progress` + `sub_stage=meeting_booked` 推送
`person:qr_ready`	个人二维码已生成	当前审核链接流程实际通过 `link:progress` + `sub_stage=qr_ready` 推送

ACME 事件 (`action_type = acme`)

ACME 自动化对接的投递事件，仅 ACME v2 订单产生，对非 ACME 账户零噪音。四个事件默认订阅，可在账户回调设置中退订。

action_id	含义	说明
`acme:account_created`	ACME 客户端已创建	ACME 账户注册（newAccount）完成；携带 `order_id`（EAB 绑定的订单）与 `acme_client`
`acme:account_deactivated`	ACME 客户端已停用	客户端通过 ACME 协议接口自行停用账户；控制台吊销客户端不触发此事件
`acme:certificate_issued`	ACME 证书已签发	客户端下载证书成功后触发；携带 `order_id`、`cert_id`、`acme_cert`（含 `full_chain_pem` 完整链）与 `acme_client`
`acme:cert_revoked`	ACME 证书已吊销	证书吊销完成；携带 `order_id`、`cert_id`、`acme_cert`（含 `cert_pem` 被吊销证书）与 `acme_client`

ACME 事件携带的专属对象：

acme_client — ACME 客户端信息：

字段	类型	说明
`id`	string	ACME 账户 ID
`account_id`	string	所属客户 ID
`last_user_agent`	string	客户端最近一次请求的 User-Agent
`ip`	string	客户端最近一次请求的来源 IP
`status`	string	ACME 账户状态，如 `valid` / `deactivated`
`last_access_at`	integer	最近访问时间（Unix 秒）

acme_cert — ACME 证书信息，仅证书事件携带：

字段	类型	说明
`sha1`	string	证书 SHA1 指纹（大写 hex）
`status`	string	`issued` / `revoked`
`common_name`	string	证书 CommonName，为空时回退首个 SAN
`full_chain_pem`	string	完整证书链 PEM，仅 `acme:certificate_issued` 携带
`cert_pem`	string	被吊销证书的 PEM（仅叶子证书），仅 `acme:cert_revoked` 携带
`product_name`	string	产品名称

幂等与归属

证书事件按账户 + 事件 + 证书终身幂等，客户端重复下载或重复吊销不会重复投递。
acme:cert_revoked 允许跨账户吊销（持证书私钥即可发起），载荷中的 acme_client 是签发账户的客户端信息，而非操作方；签发账户信息缺失时整个 acme_client 字段不携带。

acme:certificate_issued 载荷示例：

json

{
  "action_type": "acme",
  "action_id": "acme:certificate_issued",
  "order_id": "TIT6R0qv",
  "cert_id": "4itFJOgL",
  "message": "ACME 证书 example.com 已签发",
  "acme_client": {
    "id": "acct-9f3k2d",
    "account_id": "OzoYkaZ0",
    "last_user_agent": "lego/4.25",
    "ip": "203.0.113.10",
    "status": "valid",
    "last_access_at": 1760313600
  },
  "acme_cert": {
    "sha1": "A1B2C3D4E5F6...",
    "status": "issued",
    "common_name": "example.com",
    "full_chain_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
    "product_name": "TrustAsia DV SSL"
  }
}

云签电子签名认证证书事件 (`action_type = esign`)

云签电子签名认证证书（eSign）托管场景的三个推送事件。复用上文同一套投递与鉴权机制，仅事件类型与数据结构为 esign 专属。

action_id	含义
`esign:cert_issued`	云签电子签名认证证书签发并回推托管成功，携带证书 PEM 材料
`esign:grant_ready`	预授权（两步签署）完成，交付 `grantId` 与授权 Token
`esign:delegate_ready`	委托授权生效，交付 `willId` 与 `delegateId` 标识（⚠️ 由 CertCloud 轮询驱动，不承诺时效）

时间戳/整数为 JSON 数字，不是字符串

esign 对象内的毫秒时间戳（validUntil / signGrantTokenExpireAt / businessCompletedAt）与计数（usageLimit / usageRemaining）均为 JSON 数字，usageLimitEnable 为 JSON 布尔。这是 CertCloud 自有的出站回调契约，与云签入站接口「长整型一律为字符串」的口径不同，请按数字类型解析。

`esign:cert_issued` — 证书签发托管成功

esign 对象字段：

字段	类型	说明
`certId`	string	云签侧证书 ID
`orderNo`	string	CertCloud 订单号（下方「两个事件的任务号/订单号字段名不同」语义说明）
`status`	string	证书状态，恒为 `"NORMAL"`（本事件仅在托管成功后触发）
`certPem`	string	叶子证书 PEM
`chainPem`	string[]	上级证书链 PEM（从签发 CA 起的数组，可能为空）

json

{
  "action_type": "esign",
  "action_id": "esign:cert_issued",
  "message": "esign certificate issued",
  "esign": {
    "certId": "CS-CERT-XXXXX",
    "orderNo": "ORD-20250101-001",
    "status": "NORMAL",
    "certPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "chainPem": [
      "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
    ]
  }
}

与 order:issued 的关系：esign:cert_issued 是面向云签托管场景的补充推送：相较通用的订单已签发 order:issued，它额外直接携带证书材料（certPem / chainPem），供托管方无需再拉取即可入库。接入方仍按 CertCloud 订单号 orderNo 与自身订单对账。

`esign:grant_ready` — 预授权完成、Token 交付

esign 对象字段：

字段	类型	说明
`grantId`	string	预授权 ID
`certId`	string	云签侧证书 ID
`signTaskId`	string	签署任务号（创建预授权时调用方传入，非 CertCloud 订单号；2026-08-03 起由 `orderNo` 更名而来，见下方语义说明）
`usageLimitEnable`	boolean	次数模式（2026-09-04 新增，恒携带）：`true` 有限次数、`false` 不限次数。历史事件补发亦为 `true`
`usageLimit`	number	预授权总次数。仅有限次数携带，不限次数缺省
`usageRemaining`	number	剩余可用次数。仅有限次数携带，不限次数缺省——勿把缺失当作 0
`validUntil`	number	预授权有效期截止（毫秒时间戳）。不限次数同样受其约束
`signGrantToken`	string	敏感授权 Token（明文，见下方须知）
`signGrantTokenExpireAt`	number	Token 失效时间（毫秒时间戳）

json

{
  "action_type": "esign",
  "action_id": "esign:grant_ready",
  "message": "esign sign grant ready",
  "esign": {
    "grantId": "GRANT-XXXXX",
    "certId": "CS-CERT-XXXXX",
    "signTaskId": "SIGNTASK-20250101-001",
    "usageLimitEnable": true,
    "usageLimit": 100,
    "usageRemaining": 100,
    "validUntil": 1730000000000,
    "signGrantToken": "eyJ...授权明文...",
    "signGrantTokenExpireAt": 1730600000000
  }
}

signGrantToken 是敏感凭据

signGrantToken 等同于「免逐次确认的签名授权」，明文仅经 HTTPS body 交付。它不是「一次性」凭据——多次预授权（multiGrant）下同一 Token 会反复用于凭预授权 Token 签名、每次扣减 1 次额度，直至额度耗尽 / 过期 / 撤销才失效，请勿在首次签名后销毁。

接入方须按敏感凭据保存：勿写入日志、勿拼入 URL、勿下发到前端，仅在服务端保存并按需携入签名接口。

grantId 双通道：回调加速，主动查询兜底；Token 双通道：回调加速，拉取兜底

grantId 有两条获取通道，二选一即可：

回调推送（本事件）——预授权完成后由 CertCloud 主动推送，加速交付；
主动查询——经查询意愿结果按创建预授权时的 willId 查询，businessStatus=SUCCEEDED 后即可取得（不含 Token）。

Token 同样有两条获取通道，二选一即可：

回调推送（本事件）——预授权完成后由 CertCloud 主动推送，与 grantId 一并交付；
主动拉取——GET /openapi/v3/esign/sign-grants/{grantId}/token（见领取预授权 Token），可重复领取。

本回调是 grantId 与 Token 加速交付的通道，而非唯一入口：grantId 未及时收到回调时，可凭创建预授权时的 willId 经查询意愿结果主动查得；拿到 grantId 后再凭其经主动拉取补齐 Token。查询预授权状态本身以 grantId 为入参，用于拿到 grantId 之后的额度对账，不用于首次获取 grantId。

两个事件的任务号/订单号字段名不同

2026-08-03 起两者已用不同字段名区分，不再共用 orderNo：

esign:cert_issued.orderNo = CertCloud 订单号——与创建订单响应、云签证书标识映射查询所用的订单 ID 为同一值，是证书签发对账的锚点。该事件字段名不变。
esign:grant_ready.signTaskId = 签署任务号——即调用方创建预授权签署（B8）时自行传入的 signTaskId（原 orderNo，已更名），不是 CertCloud 订单号。预授权对账请以 grantId 为锚。

`esign:delegate_ready` — 委托授权生效

新增委托人发起的委托授权双方均确认后，在云签侧真正生效（businessStatus=SUCCEEDED）时推送本事件。

前提条件与触发时机

与其他事件一样，本事件仅在账户配置了回调 URL（「账户设置 → 回调地址设置」）时才会推送。

本事件在委托授权真正生效时才推送，不是双方在意愿页完成确认（willStatus=CONFIRMED）就推送——确认完成后，业务生效仍在云签侧异步发生，两者是两回事，语义与本文档其余意愿类事件一致。

⚠️ 本事件当前由 CertCloud 轮询云签结果后驱动推送，不承诺时效；对时效敏感的场景请同时以查询意愿结果轮询兜底。

esign 对象字段：

字段	类型	说明
`willId`	string	发起新增委托人时返回的意愿 ID
`delegateId`	string	委托人人员 ID，即新增委托人响应中的 `delegateId`，代签时作为 `signerId` 使用
`businessCompletedAt`	number	委托业务生效的毫秒时间戳

json

{
  "action_type": "esign",
  "action_id": "esign:delegate_ready",
  "message": "esign delegate authorization ready",
  "esign": {
    "willId": "will-xxx",
    "delegateId": "delegate-xxx",
    "businessCompletedAt": 1784457961968
  }
}

载荷只含标识，明细须另行查询

本事件的 esign 对象只携带标识字段，不携带逐证书的授权明细（生效期、证书列表等）。需要明细时，接入方应凭 delegateId（配合相应 certId）经查询委托授权记录主动查询，本事件仅用于加速感知「该委托已生效」这一事实，不替代查询接口。

esign 事件的幂等去重

esign 回调载荷内没有独立的 eventId，按 action_id 分事件去重：

esign:cert_issued 以 action_id + esign.orderNo（CertCloud 订单号）+ esign.certId 组合去重；
esign:grant_ready 以 action_id + esign.grantId 去重（grantId 唯一标识一次预授权；勿用 signTaskId——它是签署任务号，同一任务多次预授权会重复）；
esign:delegate_ready 以 action_id + esign.willId 去重（一个委托授权意愿只推送一次）。

同一键的重复推送应视为同一事件（托管重推、投递重试均可能再次到达）。

请求示例

json

{
  "action_type": "order",
  "action_id": "order:issued",
  "order_id": "ORD-20250101-001",
  "order_status": "issued",
  "cert_id": "CERT-XXXXX",
  "message": "订单 ORD-20250101-001(example.com) 已经成功签发"
}

json

{
  "action_type": "order",
  "action_id": "order:renewaled",
  "order_id": "ORD-OLD-001",
  "order_status": "renewed",
  "cert_id": "CERT-OLD-001",
  "renew_order_id": "ORD-NEW-001",
  "renew_cert_id": "CERT-NEW-001",
  "message": "订单 ORD-OLD-001(example.com) 已完成续费"
}

json

{
  "action_type": "link",
  "action_id": "link:progress",
  "link_id": "AL-EXAMPLE-001",
  "sub_stage": "qr_ready",
  "message": "二维码已生成"
}

配置、订阅与测试

使用查询回调配置查看当前 URL、停用状态和 enabled_actions，响应不会回显鉴权密钥。
使用更新回调配置局部轮换 URL 或鉴权密钥，也可以设置事件白名单。未传字段保持不变。
enabled_actions=null 表示兼容存量的全订阅；[] 表示不投递任何可过滤事件；非空数组表示只投递指定 action_id。白名单在事件进入回调队列时生效，重新开启后不会补发此前被过滤的事件。
disabled=true 会停用回调；停用时被取消的投递在重新启用后不会自动补发。
使用测试回调配置会真实发送一条模拟 order:issued 回调，但不会保存请求中的 URL 或鉴权密钥。测试不受 disabled 和 enabled_actions 限制。

重试策略与注意事项

重要行为

成功判定：接收方必须返回 HTTP 200。响应体内容不会作为成功条件。
网络错误：请求发送失败时，系统约 5 分钟后重试。
非 200 响应：回调创建后 1 小时内约每 10 分钟重试一次；超过 1 小时后约每 1 小时重试一次；超过 3 天仍未成功则取消投递。
订单已签发 / 重颁发回调：回调体通常含 cert_id，客户端可调用获取证书详情下载证书。
多年期证书续期提醒：order:cert_renew 在证书进入续期窗口后可能每天触发一次，直至证书过期或完成续期。
未知事件兼容：建议接收方按 action_id 做白名单处理，并对未知字段保持兼容，避免新增回调字段导致解析失败。
云签电子签名认证证书回调（action_type == esign）：与上述事件共用同一应答与重试策略（HTTP 200 停止投递，非 200 按上述节奏重试）。由于重试可能重复送达，请务必按幂等去重规则处理；对同一 grantId 的 signGrantToken 应幂等入库（重试不重复落库），但该 Token 可在额度窗口内反复用于签名、勿在首签后销毁；并以主动拉取 Token 作为对账与兜底通道。

业务流程

订单管理

ACME

证书管理

电子签名服务

审核链接

签名意愿

预授权签署（两步调用）

凭据管理（签署 PIN / TOTP）

证书标识与状态

密钥管理

人员信息变更

委托授权（仅企业证书）

组织管理

域名管理

账户设置

API 回调

回调地址要求

请求字段

事件列表

订单事件 (`action_type = order`)

证书事件 (`action_type = cert`)

域名预审核事件 (`action_type = domain`)

组织预审核事件 (`action_type = org`)

审核链接事件 (`action_type = link`)

个人事件 (`action_type = person`)

ACME 事件 (`action_type = acme`)

云签电子签名认证证书事件 (`action_type = esign`)

`esign:cert_issued` — 证书签发托管成功

`esign:grant_ready` — 预授权完成、Token 交付

`esign:delegate_ready` — 委托授权生效

esign 事件的幂等去重

请求示例

配置、订阅与测试

重试策略与注意事项

相关文档

订单管理

ACME

证书管理

组织管理

域名管理

API 回调 ​

回调地址要求 ​

请求字段 ​

事件列表 ​

订单事件 (action_type = order) ​

证书事件 (action_type = cert) ​

域名预审核事件 (action_type = domain) ​

组织预审核事件 (action_type = org) ​

审核链接事件 (action_type = link) ​

个人事件 (action_type = person) ​

ACME 事件 (action_type = acme) ​

云签电子签名认证证书事件 (action_type = esign) ​

esign:cert_issued — 证书签发托管成功 ​

esign:grant_ready — 预授权完成、Token 交付 ​

esign:delegate_ready — 委托授权生效 ​

esign 事件的幂等去重 ​

请求示例 ​

配置、订阅与测试 ​

重试策略与注意事项 ​

相关文档 ​

API 回调

回调地址要求

请求字段

事件列表

订单事件 (`action_type = order`)

证书事件 (`action_type = cert`)

域名预审核事件 (`action_type = domain`)

组织预审核事件 (`action_type = org`)

审核链接事件 (`action_type = link`)

个人事件 (`action_type = person`)

ACME 事件 (`action_type = acme`)

云签电子签名认证证书事件 (`action_type = esign`)

`esign:cert_issued` — 证书签发托管成功

`esign:grant_ready` — 预授权完成、Token 交付

`esign:delegate_ready` — 委托授权生效

esign 事件的幂等去重

请求示例

配置、订阅与测试

重试策略与注意事项

相关文档