更新回调配置

PUT

/openapi/v3/account/callback

局部更新当前账户的回调配置。请求体至少包含一个字段；未传字段保持不变。

Body 参数 application/json

参数	类型	必填	说明
url	string	否	回调地址，必须使用 HTTPS，去除首尾空白后最长 256 个字符
access_key	string	否	回调鉴权密钥，去除首尾空白后最长 256 个字符；投递时写入 X-CC-Callback-Auth 请求头
disabled	boolean	否	true 表示停用业务回调，false 表示启用
enabled_actions	string[] / null	否	完整替换事件订阅白名单，最多 200 项；[] 表示不投递任何可过滤事件

首次配置

账户尚未配置回调时，首次调用必须同时传入 url 和 access_key。之后可以只提交需要轮换或修改的字段。

enabled_actions 三态

不传该字段（或传 JSON null）时保留原值；传 [] 时关闭所有可过滤事件；传非空数组时仅订阅指定事件。不能通过本接口把该字段恢复为 null。详细说明见账户回调配置。

请求示例

轮换回调 URL 中的网关令牌，并更新订阅事件：

curl -X PUT 'https://api.certcloud.cn/openapi/v3/account/callback' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "url": "https://gateway.example.com/callback?token=new-token",
    "enabled_actions": ["order:issued", "order:renewaled", "cert:expired"]
  }'

首次创建配置：

curl -X PUT 'https://api.certcloud.cn/openapi/v3/account/callback' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "url": "https://gateway.example.com/callback",
    "access_key": "your-callback-access-key",
    "disabled": false,
    "enabled_actions": ["order:issued", "order:renewaled"]
  }'

200成功

{
  "code": "success"
}

生效说明

• 新产生的事件会在下一投递扫描周期使用更新后的 URL、鉴权密钥和停用状态。
• 已入队但投递失败的事件不会因更新而立即重发；其原有 next_try_at 到期后，会使用最新配置重试。
• 配置建立前因未配置回调而未入队的历史事件不会补发。
• 白名单在业务事件创建回调记录时判断，不会补发此前因未订阅而被过滤的事件。
• disabled=true 时被取消的投递，在重新启用后不会自动补发。
• 建议先调用测试回调配置验证新地址和鉴权密钥，再保存变更。

相关错误码

code	说明
invalid_parameters	请求体为空、URL 或鉴权密钥为空
invalid_callback_url	URL 格式无效，或 URL/鉴权密钥超过长度限制
callback_url_not_https	URL 未使用 HTTPS
callback_not_configured	首次配置未同时提供 URL 和鉴权密钥
invalid_callback_action	enabled_actions 包含不支持的事件
callback_actions_too_many	enabled_actions 超过 200 项
callback_action_mpki_unsupported	MPKI 账户选择了 MPKI 通道不支持的事件
callback_setting_not_found	并发更新期间配置已不存在，请重新查询后重试
permission_denied	当前 API Key 或账户不允许执行该修改

完整列表见错误码说明。