服务端通知

服务端通知，是指从世游服务端发起的，到游戏服务端的 server-to-server 的 HTTP 调用。

HTTP 调用的标准由世游定义，游戏服务端负责对通知进行处理。

服务端通知总是使用 HTTP POST。

警告

为了通信的安全性，游戏服务端必须通过 HTTPS 对外服务，且必须支持 TLS 1.2 及以上。

请求鉴权

服务端通知预期游戏侧对请求进行鉴权的方式，是 HTTP Request Signing。

签名方式请阅读 签名算法。

签名过程中使用的 Game ID 由世游分配。 签名使用的私钥，使用世游为每个游戏项目生成的 Secret Key。

如果请求的签名验证不通过，预期游戏服务端应当返回 HTTP 401 Unauthorized。

危险

游戏侧应当重视 Secret Key 的安全性，将其妥善保管，严格控制密钥的访问权限，并安全地分发至游戏服务器的运行环境。

请注意，Secret Key 一定不能放在客户端。

通知端点

• 创建订单 传入的 notify_url 通知端点，该端点用于 订单类通知。
• 世游发行平台 配置的 notify_url 通知端点，该端点用于 其它通知。

建议将两个通知端点设置为同一个地址，通过解析 HTTP Request Body 来区分 通知类型，参考示例：

https://webhook.example.com/combo/notifications

通知请求

通知请求的 Content-Type 总是 application/json。

Request Body 为包含以下属性的 JSON Object。

Property	Type	Description
version	string[1,16]	世游服务端通知的版本号。当前版本固定为 1.0。
notification_id	string[1,64]	每次通知的唯一 ID。游戏侧可用于日志记录、调试、问题排查。
notification_type	string[1,32]	用于标识通知类型，data 中的结构随着通知类型的不同而不同。
data	object	与 notification_type 对应的结构，是一个异构的 JSON Object。

通知响应

• 游戏侧收到通知后，需要在 5 秒内响应，否则会认为通知失败，后续会重复发送通知。
• 相同的通知可能会多次发送给游戏侧，游戏侧必须能正确处理重复的通知（幂等性处理），如果已经处理过，则直接返回成功。
• 如果游戏侧处理通知成功，应返回 HTTP 200。世游侧会认为此次通知被正常接收。
• 如果游戏侧处理通知失败，应返回 HTTP 50x 或 HTTP 40x。世游侧会按照 重试策略 自动重新发起通知。
• 服务端通知从功能上并不要求游戏侧在 Response Body 中返回数据。但建议游戏侧选择在 Response Body 中返回任意的 text/plain 文本内容用于辅助双方调试。

通知类型

所有通知类型可分为两大类：

• 订单类通知 ：订单发货 、订单退款
• 其它通知 : 数据标签 、账号封禁、账号删除 等（部分开发中）

订单发货

通知游戏服务端对订单发货。

此时 notification_type 字段的值为 ship_order。

此时 data 包含以下字段：

Property	Type	Required	Description
order_id	string[1,64]	True	世游服务端创建的，标识订单的唯一 ID。
reference_id	string[8,64]	True	游戏侧用于标识创建订单请求的唯一 ID。
combo_id	string[1,64]	True	发起购买的用户的唯一标识。
product_id	string[1,64]	True	购买的商品 ID。
quantity	integer	True	购买的商品的数量。
currency	string[3]	True	订单币种代码。例如 USD CNY。
amount	integer	True	订单金额，单位为分。
context	string[1,255]	False	游戏侧创建订单时提供的订单上下文，透传回游戏。
is_sandbox	bool	False	标识通知的订单是否是沙盒订单, True 表示是沙盒订单，缺省或者 False 表示非沙盒订单。

信息

订单发货通知地址会使用游戏服务端调用 create-order 时传入的 notify_url。

游戏服务端接收到通知后，主要需要关注以下几点：

1. 根据 签名算法 计算请求的签名，并验证签名正确性。
2. 校验 order_id 和 refernence_id 是否存在，以及是否重复发货，如果重复发货，需要游戏服务端进行幂等处理。
3. 校验订单中的 product_id，quantity，currency，amount 字段，确保订单内容正确。

订单退款

通知游戏服务端订单已经被退款。

此时 notification_type 字段的值为 refund。

此时 data 包含以下字段：

Property	Type	Required	Description
order_id	string[1,64]	True	世游服务端创建的，标识订单的唯一 ID。
reference_id	string[8,64]	True	游戏侧用于标识创建订单请求的唯一 ID。
combo_id	string[1,64]	True	发起购买的用户的唯一标识。
product_id	string[1,64]	True	购买的商品 ID。
quantity	integer	True	购买的商品的数量。
currency	string[3]	True	订单币种代码。例如 USD CNY。
amount	integer	True	订单金额，单位为分。
context	string[1,255]	False	游戏侧创建订单时提供的订单上下文，透传回游戏。
is_sandbox	bool	False	标识通知的订单是否是沙盒订单, True 表示是沙盒订单，缺省或者 False 表示非沙盒订单。

信息

订单退款通知地址会使用游戏服务端调用 create-order 时传入的 notify_url。

游戏侧可能需要对退款通知进行对应处理，例如扣除玩家充值获得的金币、道具等。

退款通知主要有以下用途：

1. 对账：财务会对游戏侧、世游侧、应用商店侧三方的支付流水进行对账。
2. 数据分析：有些玩家可能会通过退款刷道具。针对这种 "恶意" 退款的玩家，游戏侧可以通过数据分析识别出这些玩家，并对其封号。

危险

当前支持退款通知的应用商店包括 App Store、华为、鸿蒙、荣耀，未来可能会有更多应用商店支持退款通知。

游戏侧在实现退款通知处理逻辑时，不应假设退款通知只来自特定应用商店，而应当对所有退款通知进行统一处理。这样当新的应用商店接入退款能力时，游戏侧无需做任何改动即可自动适配。

数据标签

通知游戏服务端一批数据标签。

此时 notification_type 字段的值为 data_tags。

此时 data 包含以下字段：

Property	Type	Required	Description
tags	array[Tag]	True	数据标签数组，数组长度不定，每个元素的结构见 Tag。

Tag

Property	Type	Required	Description
entity_type	string[1,32]	True	标签所属实体的类型。例如 role 代表实体类型为游戏角色。
entity_id	string[1,64]	True	标签所属实体的唯一标识。
tag_name	string[1,64]	True	标签名称。
tag_value	string[1,255]	True	标签值。

信息

数据标签通知目前仅对特定游戏开放。

预期游戏侧在接收到数据标签通知后，将这些数据标签持久化存储。

数据标签通知涉及的数据量较大。为避免影响订单类通知（例如订单发货）接收服务的稳定性，可以将订单类通知与其它通知拆分到两个不同的通知端点 URL 分别接收。该方案按游戏的实际需求采用，并非强制要求。

重试策略

如果游戏侧在处理通知时未能按预期返回 HTTP 200，则世游服务端会按照以下策略进行重试：

在 168h 中发起最多 90 次重试，通知频率为 15s/30s/1m/2m/4m/8m/16m/32m/1h4m/2h/2h/2h/...