处理同步回调

同步回调要求接收端在一次 HTTPS 请求内返回结构化结果。它与异步事件分别配置；选择长连接接收事件，不会将同步回调改为长连接。

当前可配置 token.agent.action.v1 并在 Sandbox 发送合成测试。真实 TOKEN 业务调用尚未开放；保存配置或测试成功，不代表生产业务已经使用该回调。

配置与测试

1. 在当前 Sandbox 应用的“开发接入 → 事件与 Webhook → 回调配置”选择回调类型。
2. 配置公网 HTTPS 接收地址，通过地址校验，按当前配置准备验签、Verification Token 和解密。
3. 保存后发送一次合成测试，查看独立的回调结果及接收端记录。

配置保存失败时，按配置恢复处理。配置保存的恢复与已发送测试的结果核对分别进行，不会自动再次发送测试。

异步事件集合和同步回调集合独立保存，修改一个集合时保留另一个完整集合。URL 变化后须重新校验。测试可能执行接收端逻辑，须使用明确隔离的测试处理；测试请求会标记 X-GV-Test-Delivery: true。

接收请求

先按当前配置验证签名、Token 和加密 Body，再验证请求 Schema、当前应用及环境。移除传输安全字段后，请求信封示例如下；所有标识均为合成值。

{
  "schema_version": "1",
  "request_id": "callback-example-001",
  "callback_type": "token.agent.action.v1",
  "application_id": "application_opaque",
  "environment": "sandbox",
  "data": {"action": "check"}
}

名称	类型	必填	说明
schema_version	string	🔴 必填	当前固定为 "1"
request_id	string	🔴 必填	原样返回，用于接收端防重复
callback_type	string	🔴 必填	token.agent.action.v1
application_id、environment	string	🔴 必填	核对接收端应用和环境
data	object	🔴 必填	应用约定的 JSON，最多 64 KiB

不要用异步事件的 event_id 或租约 ACK 替代同步请求标识。签名、加密和凭据取得方式见接收 Webhook。

返回结果

在 5 秒内返回 application/json，完整响应最多 64 KiB。信封只能包含下列五个字段；重复字段、未知字段、错误请求标识或非对象结果会被拒绝。

{
  "schema_version": "1",
  "request_id": "callback-example-001",
  "callback_type": "token.agent.action.v1",
  "status": "completed",
  "result": {"accepted": true}
}

名称	类型	必填	说明
schema_version	string	🔴 必填	固定为 "1"
request_id	string	🔴 必填	与请求完全一致
callback_type	string	🔴 必填	与请求完全一致
status	string	🔴 必填	completed 或 rejected
result	object	🔴 必填	应用约定的 JSON 对象

仅返回 2xx 而没有合法结果，不表示回调完成。

超时与结果未知

每个请求标识只尝试一次，平台不会自动重试外部动作。超时、断线或 503 可能表示接收端已处理但结果未返回；先按原 request_id 查询接收端结果，不能把换新标识重发当作恢复。

相同请求标识再次提交会返回 409，不会再次执行接收端效果。只有核对结果并决定发起一次新的测试时，才使用新标识。接收端自身仍须防重复并避免重复业务副作用。

情况	处理方式
地址变化或未通过校验	在当前应用校验实际接收地址，再保存配置
签名、Token 或解密失败	拒绝请求并核对当前接收端凭据，保留不含敏感值的诊断
结果字段、类型或标识不匹配	修正响应，按原请求标识核对接收端结果
超时、断线或 503	先核对原请求结果；不自动重发外部动作
409，请求标识已使用	查询原请求结果；需要一次新测试时再明确生成新标识

下一步：长连接接收事件 · 事件目录 · 支持与问题诊断

请求头 X-GV-Callback-ID 与请求标识一致。签名、Token、加密 Body 和完整业务正文均不写入普通日志。