C5GAME 订单回调通知服务——让你的系统自动感知交易状态变化

什么是回调通知？

当你通过 C5GAME API 发起一笔交易后，你需要知道这笔交易当前的状态是什么——是还没发货、已经发货了、还是交易完成了。有两种方式获取状态：

方式一：主动查询（Pull）

• 你定时调用"订单查询"接口获取最新状态
• 实现简单，但有延迟（取决于查询频率），且高频查询可能触发频率限制

方式二：回调通知（Push / Webhook）

• C5GAME 在订单状态发生变化时，主动向你指定的服务器地址推送一条消息
• 几乎零延迟，不需要你轮询查询
• 是更推荐的方式

C5GAME 开放平台提供了完整的回调通知服务，覆盖了订单生命周期的主要状态变更。

回调通知的工作流程

1. 你在 C5GAME 开放平台配置一个回调 URL（你的服务器地址）
2. 通过 API 发起交易
3. 交易生命周期中状态发生变化时：
   - 买家付款成功 → C5GAME 推送通知到你的回调 URL
   - 卖家发货（Steam 报价发出）→ C5GAME 推送通知
   - 买家接受报价 → C5GAME 推送通知
   - 交易完成 → C5GAME 推送通知
   - 订单取消或失败 → C5GAME 推送通知
4. 你的服务器接收 POST 请求，解析 JSON 数据，处理后续逻辑
5. 处理完后返回一个成功响应（HTTP 200）给 C5GAME

回调通知的状态字段详解

C5GAME 回调通知里最关键的是 status 字段，它告诉你订单当前处于什么状态：

不同版本的开放平台可能还有更多状态值，以最新文档为准。

回调通知的重试策略

网络不可靠——你的服务器可能临时宕机、网络抖动、或者处理超时。为了保证通知最终送达，C5GAME 采用了指数退避重试机制：

重试时间间隔：1 分钟 → 2 分钟 → 5 分钟 → 10 分钟 → 30 分钟

如果你连续 N 次（通常 5 次）都没有成功接收（返回非 200 状态码或超时），C5GAME 会停止重试。

你的接收端需要做什么？

要正确接收和处理 C5GAME 的回调通知，你的服务器需要：

1. 暴露一个公网可访问的 HTTP POST 端点

• 这个 URL 必须能被 C5GAME 的服务器访问到
• 建议使用 HTTPS（虽然 HTTP 也可以，但 HTTPS 更安全）

2. 正确处理 POST 请求

• C5GAME 发送的 Content-Type 通常是 application/json
• 请求体是 JSON 格式，包含订单信息和状态
• 你需要解析 JSON 并提取关键字段

3. 做签名验证（重要！）

• C5GAME 会在请求头或参数里带一个签名（sign）
• 你需要用 C5GAME 给你的 API Secret 重新计算签名，对比是否一致
• 签名不一致说明请求可能是伪造的，应该拒绝处理

4. 返回正确的响应

• 处理成功后，返回 HTTP 200 状态码
• 失败则返回 4xx 或 5xx，让 C5GAME 继续重试

5. 做好幂等处理

• 同一个订单状态变化可能被 C5GAME 多次推送（重试机制）
• 你的处理逻辑需要能应对"同一个状态被处理两次"的情况——通常做法是在数据库里记录每个订单的已处理状态，重复请求直接忽略

回调数据结构示例

根据 C5GAME 公开文档，回调通知的数据大致结构如下（简化版）：

{
  "status": 3,
  "orderId": "C52025010112345678",
  "actualPay": 14800,
  "sellerInfo": {
    "nickName": "全自动秒出",
    "avatar": "https://c5game.oss-cn...avatar.jpg"
  },
  "offerId": "OFFER_12345",
  "time": 1735776000
}

各字段含义：

• status：订单状态码（见上文表格）
• orderId：C5GAME 订单 ID（全平台唯一）
• actualPay：实际支付金额（单位：分）
• sellerInfo：卖家信息
• offerId：Steam 交易报价 ID（仅 status=3 时可用，用于在 Steam 端找到对应报价）
• time：通知发送时间戳（Unix 秒）

接入回调的注意事项

• 回调 URL 必须公网可达——本地 localhost 不行，需要有公网 IP 或域名
• 超时设置要合理——C5GAME 对回调请求的超时时间通常是 5 秒，你的处理逻辑要在 5 秒内返回
• 签名验证不要省略——任何人都可以向你的回调 URL 发 POST 请求，如果不验签就会收到伪造通知
• 建议保存所有原始回调数据——用于后续排错和审计
• 回调只是辅助——不要只依赖回调，定期主动查询订单状态作为兜底

常见问题

Q：为什么我收不到回调？ A：按这个顺序排查：①回调 URL 是否公网可达；②服务器防火墙/安全组是否放行了 C5GAME 的请求 IP；③你的处理端是否在 5 秒内返回了 200；④签名是否正确。

Q：同一个状态收到多次回调怎么办？ A：这是正常的（重试机制）。你需要在处理逻辑里做幂等——比如用 (orderId, status) 作为联合键，已处理的直接跳过。

Q：回调通知会延迟吗？ A：正常情况下 C5GAME 状态变化后几秒内就会推送。但网络波动、C5GAME 服务器繁忙等情况可能导致延迟。超过 1 分钟没收到可以主动查询。