Appearance
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 |
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 | 按需 | 当前订单状态，订单/证书相关事件可能携带 |
事件列表
订单事件 (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 | 二维码已生成 |
个人事件 (action_type = person)
| action_id | 含义 | 说明 |
|---|---|---|
person:meeting_booked | 个人面审预约成功 | 当前审核链接流程实际通过 link:progress + sub_stage=meeting_booked 推送 |
person:qr_ready | 个人二维码已生成 | 当前审核链接流程实际通过 link:progress + sub_stage=qr_ready 推送 |
请求示例
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) 已经成功签发"
}配置、订阅与测试
- 使用查询回调配置查看当前 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做白名单处理，并对未知字段保持兼容，避免新增回调字段导致解析失败。