设置Webhook
Webhook是系统中发生的事件的通知。发生特定事件时，艾克索拉会向您的应用程序发送一个传送事件数据的HTTP请求，通常是JSON格式的POST请求。
事件示例：
- 用户与商品目录进行了交互
- 支付或取消了订单
Webhook列表
艾克索拉侧设置了两种接收商品购买和退款Webhook的方式——付款及交易数据信息和所购商品信息可以分开发送，也可以合并到一个Webhook中。
如需切换到接收合并Webhook的新方式，请联系您的客户成功经理或发送邮件至[email protected]。
要实现游戏内商店和支付管理的完整功能，必须实现对主要Webhook的处理：
如您的应用程序侧实现了商品目录个性化，请设置合作伙伴侧目录个性化的处理。
在发布商帐户中设置Webhook
要启用Webhook接收：
- 在发布商帐户中打开您的项目。
- 在侧边栏中单击项目设置，然后前往Webhooks选项卡。
- 在Webhook服务器字段中指定要接收Webhook的服务器URL，格式为
https://example.com。您也可以指定在工具中找到的URL来用于测试。
- 默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥，请点击刷新图标。
- 单击启用Webhook。
在Webhook服务器字段中保存URL时，可看到高级设置部分，其中可以授予在Webhook中接收详细信息的权限。方法是将所需开关设置为打开。在每个权限所在行，您可以看到受该设置影响的Webhook列表。
- 在发布商帐户中打开您的项目。
- 在侧边栏中单击项目设置，然后前往Webhooks选项卡。
- 单击禁用Webhook。
在发布商帐户中测试Webhook
如成功设置了Webhook，Webhook设置区块下方会显示一个Webhook测试区块。
发布商帐户中的测试部分会根据Webhook接收方式不同而有所不同。
下方介绍了合并Webhook场景的测试流程。
在付款和商店选项卡中，您可以测试以下Webhook：
要进行测试：- 在Webhook测试部分，前往付款和商店选项卡。
- 在下拉菜单中选择商品类型。如所选类型的商品未在发布商帐户中设置，请单击：
- 连接 – 如未连接该商品类型的模块
- 配置 – 如之前已连接了该模块但未完成设置
- 填写必填字段：
- 从下拉列表中选择商品SKU并指定金额。您可以通过单击+并在新行中添加来选择同一类型的多个商品。
- 用户ID — 测试阶段可使用任意字母数字组合。
- 公共用户ID — 对用户显示的ID，例如邮箱或昵称。仅当在支付中心 > 设置部分为项目启用了公共用户ID时才会显示此字段。
- 在艾克索拉订单ID字段中输入任意值。
- 艾克索拉发票ID — 艾克索拉侧的交易ID。测试阶段可使用任意数值。
- 发票ID — 游戏侧的交易ID。测试阶段可使用任意字母数字组合。它不是成功支付的必需参数，但可传入该参数来将己侧交易ID与艾克索拉侧交易ID关联起来。
- 数量 — 支付金额。测试阶段可使用任意数值。
- 货币 — 从下拉列表中选择一个货币。
- 单击测试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的响应，或收到5xx代码的响应，也将尝试重新发送Webhook且重试的间隔逐渐拉长。12小时内最多尝试12次。
如果艾克索拉服务器未收到用户验证Webhook的响应，或收到400或5xx代码的响应，将不会重新发送用户验证Webhook。
该情况下会向用户显示一个错误，且不会发送支付和订单成功支付Webhook。
配置Webhook中的商品信息
您可以通过items数组配置在订单成功支付和订单取消Webhook中包含的商品数据。
启用附加参数包含
启用以下附加参数的包含功能以标识：
- 商品是否免费(
is_free) - 商品是否为奖励(
is_bonus) - 商品是否为捆绑包内容(
is_bundle_content)
要接收这些参数，您需要使用更新Webhook设置信息API调用将Webhook切换到版本2。在版本1（默认版本）中，这些参数不可用。
包含附加参数的items数组示例：
- json
1
2"items": [
3 {
4 "sku": "com.xsolla.item_new_1",
5 "type": "bundle",
6 "is_pre_order": false,
7 "is_free": false,
8 "is_bonus": false,
9 "Is_bundle_content": false,
10 "quantity": 1,
11 "amount": "1000",
12 "promotions": []
13 },
14 {
15 "sku": "com.xsolla.gold_1",
16 "type": "virtual_currency",
17 "is_pre_order": false,
18 "is_free": false,
19 "is_bonus": false,
20 "is_bundle_content": true,
21 "quantity": 1500,
22 "amount": "[null]",
23 "promotions": []
24 }
25 ],
禁用捆绑包内容包含
默认情况下，Webhook会将捆绑包中的所有商品作为单独商品列表包含在内。您可以将Webhook配置为仅包含捆绑包本身，而不列出其内容。
在这种情况下，捆绑包中包含的商品不会出现在items数组中。在上面的数组中，SKU为com.xsolla.gold_1的商品（作为捆绑包的一部分）未被包含。
禁用捆绑包内容时的items数组示例：
- json
1
2"items": [
3 {
4 "sku": "com.xsolla.item_new_1",
5 "type": "bundle",
6 "is_pre_order": false,
7 "is_free": false,
8 "is_bonus": false,
9 "Is_bundle_content": false,
10 "quantity": 1,
11 "amount": "1000",
12 "promotions": []
13 }
14 ],
如需禁用捆绑包内容包含功能，请联系您的客户成功经理或发送邮件至[email protected]。
发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
