设置Webhook
Webhook是系统中发生的事件的通知。发生特定事件时，艾克索拉会向您的应用程序发送一个传送事件数据的HTTP请求，通常是JSON格式的POST请求。
事件示例：
- 用户与商品目录进行了交互
- 支付或取消了订单
Webhook列表
对于游戏密钥销售，无需进行用户验证和帐户中物品添加。如果您想接收付款或订单取消等事件的相关信息，可以连接Webhook。
如果连接了Webhook，请务必处理所有传入的必需Webhook。
在艾克索拉侧，针对商品购买和退款情况，有两种接收Webhook的方式：付款及交易数据信息和所购商品信息可以分开发送，也可以合并到一个Webhook中。所有新项目默认采用合并Webhook方式。
如需切换到接收合并Webhook的新方式，请联系您的客户成功经理或发送邮件至csm@xsolla.com。
要实现游戏内商店和支付管理的完整功能，必须实现对主要Webhook的处理：
| Webhook名称 | 描述 |
|---|---|
用户验证 > 用户验证(user_validation) | 在支付过程的不同阶段发送，用于确保用户已在游戏中注册。 |
游戏服务 > 合并Webhook > 订单成功支付(order_paid) | 包含支付数据、交易详情和所购商品的信息。使用此Webhook中的数据为用户添加商品。 |
游戏服务 > 合并Webhook > 订单取消(order_canceled) | 包含取消的付款的数据、交易详情和所购商品信息。使用此Webhook中的数据移除购买的商品。 |
下图显示了使用合并Webhook购买商品和退款的过程。
sequenceDiagram
participant User
participant GameClient as Game Client
participant Xsolla
participant GameServer as Game Server
%% Item Purchase
Note over User, GameServer: Item purchase
User ->> GameClient: Logs in
GameClient ->> Xsolla: Sends user authentication request
Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
Xsolla -->> GameClient: Returns array of items
GameClient -->> User: Displays storefront
User ->> GameClient: Selects item and clicks Buy
GameClient ->> Xsolla: Creates order request
Xsolla -->> GameClient: Returns payment token
GameClient ->> Xsolla: Opens payment UI URL with received token
Xsolla ->> GameServer: Sends User validation webhook
GameServer -->> Xsolla: Returns success status code
Xsolla -->> User: Displays payment UI
User ->> Xsolla: Chooses payment method and clicks Pay
Xsolla ->> GameServer: Sends Successful payment for order webhook
GameServer ->> GameServer: Grants purchases to user
GameServer -->> Xsolla: Returns success status code
Xsolla -->> User: Shows successful purchase screen
%% Refund / Chargeback
Note over User, GameServer: Refund / Chargeback
User ->> Xsolla: Requests refund or chargeback
Xsolla ->> GameServer: Sends Order cancellation webhook
GameServer ->> GameServer: Removes items from user inventory
GameServer -->> Xsolla: Returns success status code
Xsolla -->> User: Refunds the payment
如您的应用程序侧实现了商品目录个性化，请设置合作伙伴侧目录个性化的处理。
在发布商帐户中设置Webhook
要启用Webhook接收功能：
- 在发布商帐户的项目中前往设置 > Webhook部分。
- 在Webhook服务器字段中，按
https://example.com格式指定接收Webhook的服务器URL。您也可以使用Webhook测试工具中提供的URL。
- 默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥，请点击刷新图标。
- 单击启用Webhook。
在Webhook服务器字段中保存URL时，可看到高级设置部分，其中可以授予在Webhook中接收详细信息的权限。方法是将所需开关设置为打开。在每个权限所在行，您可以看到受该设置影响的Webhook列表。
- 在发布商帐户中打开您的项目，前往设置 > Webhooks部分。
- 单击禁用Webhook。
在发布商帐户中测试Webhook
当您在项目中启用Webhook后，发布商帐户的高级设置下方会显示Webhook测试区域。
您可以测试以下Webhook：
| Webhook测试的选项卡名称 | Webhook名称和类型 |
|---|---|
| 付款和商店 | 用户验证 > 用户验证(user_validation) |
游戏服务 > 合并Webhook > 订单成功支付(order_paid) | |
游戏服务 > 合并Webhook > 订单取消(order_canceled) | |
| 订阅 | 用户验证 > 用户验证(user_validation) |
付款 > 支付(payment) | |
| 争议 | 反欺诈 > 争议(dispute) |
要测试Webhook：
- 在Webhook测试部分，前往付款和商店选项卡。
- 在下拉菜单中选择游戏密钥。如果游戏密钥套餐未在项目中配置，您将看到一个前往设置的按钮。
- 填写必要字段：
- 艾克索拉订单ID — 艾克索拉侧的订单ID。测试时可使用任意数字值。
- 艾克索拉发票ID — 艾克索拉侧的交易ID。测试时可使用任意数字值。
- 商品 — 您希望在Webhook中接收其信息的商品。从下拉列表选择商品SKU并指定数量。可通过单击+并在新行添加来选择同类型的多个商品。
- 用户ID — 测试时可使用任意字母和数字组合。
- 发票ID — 游戏侧的交易ID。测试时可使用任意字母和数字组合。这不是成功支付的必需参数，但可用于关联己侧与艾克索拉侧的交易ID。
- 金额 — 支付金额。测试时可使用任意数字值。
- 货币 — 从下拉列表中选择货币。
- 单击测试Webhook。
包含指定数据的订单成功支付、订单取消和用户验证Webhook会发送到您提供的URL。每种Webhook类型的测试结果将显示在测试Webhook按钮下方。您需要为每个Webhook配置两种处理场景：成功场景和错误场景。
Webhook监听器
Webhook监听器是一个程序代码，可以在指定的URL地址接收传入的Webhook、生成签名及向艾克索拉Webhook服务器发送响应。
生成签名
接收Webhook时，应确保数据传输的安全性。为此，必须从Webhook数据生成一个签名并确保它与HTTP请求头中发送的签名匹配。
要生成签名：
- 将请求正文中的JSON与项目密钥串联起来。
- 对第一步中得到的字符串应用SHA-1加密散列函数。
向Webhook发送响应
要确认收到Webhook，您的服务器必须返回：
200、201或204HTTP代码（成功响应时）。- 带问题描述的
400HTTP代码（如未找到指定用户或传入的签名无效）。
如您的服务器发生临时问题，您的Webhook处理程序也可以返回5xx代码。
如果艾克索拉服务器未收到对订单成功支付或订单取消Webhook的响应，或收到了包含5xx代码的响应，将根据以下规则重新发送Webhook：
- 间隔5分钟尝试2次
- 间隔15分钟尝试7次
- 间隔60分钟尝试10次
自首次尝试起，12小时内最多尝试发送Webhook20次。
支付和退款Webhook的重试逻辑在各自的Webhook页面中有详细说明。
如果艾克索拉服务器未收到用户验证Webhook的响应，或收到400或5xx代码的响应，将不会重新发送用户验证Webhook。
该情况下会向用户显示一个错误，且不会发送支付和订单成功支付Webhook。
发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
