设置Webhook

Webhook是系统中发生的事件的通知。发生特定事件时，艾克索拉会向您的应用程序发送一个传送事件数据的HTTP请求，通常是JSON格式的POST请求。

事件示例：

• 用户与商品目录进行了交互
• 支付或取消了订单

Webhook列表

要完整运营一个游戏内商店，必须实现对主要Webhook的处理：

• 支付 — 订单付款时发送，包含支付数据及交易详情。
• 订单成功支付 — 成功处理支付Webhook时发送，包含所购商品及交易ID的信息。使用此Webhook的数据向用户添加商品。
• 退款 — 订单取消时发送，包含取消的付款数据及交易详情。
• 订单取消 — 成功处理退款Webhook时发送，包含所购商品及取消的交易的ID信息。使用此Webhook的数据移除购买的商品。

• 用户验证 — 在支付过程的不同阶段发送，用于确保用户已在游戏中注册。

以下是使用列表中的Webhook在网站上购买和返回产品的过程图。

如您的应用程序侧实现了商品目录个性化，请设置合作伙伴侧目录个性化的处理。

在发布商帐户中设置Webhook

要启用Webhook接收：

1. 在发布商帐户中打开您的项目。
2. 在侧边栏中单击项目设置，然后前往Webhooks选项卡。
3. 在Webhook服务器字段中指定要接收Webhook的服务器URL，格式为https://example.com。您也可以指定在工具中找到的URL来用于测试。
4. 默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥，请点击刷新图标。
5. 单击启用Webhook。

1. 在发布商帐户中打开您的项目。
2. 在侧边栏中单击项目设置，然后前往Webhooks选项卡。
3. 单击禁用Webhook。

在发布商帐户中测试Webhook

您可以测试以下Webhook的接收：

如成功设置了Webhook，Webhook设置区块下方会显示一个Webhook测试区块。

• 商店
• 支付

在商店选项卡中，可测试以下Webhook：

• 订单支付成功(order_paid)
• 订单取消(order_canceled)

要进行测试：

1. 在Webhook测试区块，前往商店选项卡。
2. 在下拉菜单中选择商品类型。如所选类型的商品未在发布商帐户中设置，请单击：
   • 连接 – 如未连接该商品类型的模块
   • 配置 – 如之前已连接了该模块但未完成设置

1. 点击该按钮后，您将跳转到发布商帐户中对应所选商品类型的部分。创建商品后，请返回Webhook测试部分，然后继续下一步。

3. 在艾克索拉订单ID字段中输入任意值。
4. 从下拉列表中选择商品的SKU并指定金额。您可以点击+选择同一类型的多个商品，将它们添加到新行中。
5. 选择支付订单的货种。
6. 单击测试。

包含所指定数据的订单成功支付和订单取消Webhook将发送到提供的URL。各Webhook类型的测试结果在测试按钮下方显示。

注：

如测试区块中显示一条测试未通过的错误消息，请检查Webhook监听器中的Webhook响应设置。测试结果中会提供相关错误信息。

在支付选项卡中，可测试以下Webhook：

• 用户验证 (user_validation)
• 支付 (payment)

要进行测试：

1. 在测试部分，前往支付选项卡。
2. 填写必填字段：
   • 用户ID — 测试阶段可使用任意字母数字组合。
   • 公共用户ID — 对用户显示的ID，例如邮箱或昵称。仅当在支付中心 > 设置 > 其他设置部分为项目启用了公共用户ID时才会显示此字段。
   • 货币 — 从下拉列表中选择一个货币。
   • 艾克索拉发票ID — 艾克索拉侧的交易ID。测试阶段可使用任意数值。
   • 数量 — 支付金额。测试阶段可使用任意数值。
   • 发票ID — 游戏侧的交易ID。测试阶段可使用任意字母数字组合。它不是成功支付的必需参数，但可传入该参数来将己侧交易ID与艾克索拉侧交易ID关联起来。
3. 单击测试Webhook。

您将在所指定的URL收到包含数据的Webhook。每个Webhook的测试结果（成功的场景和出错的场景）在测试Webhook按钮下方显示。如项目启用了公共用户ID，还可看到用户搜索检查的结果。

对于每个Webhook，均需要配置对两种场景（成功和出错）的处理。

在Webhook服务器字段中保存URL时，可看到高级设置部分，其中可以授予在Webhook中接收详细信息的权限。方法是将相应开关设置为开。在每个权限所在行，您可以看到受该设置影响的Webhook列表。

Webhook监听器

Webhook监听器是一个程序代码，可以在指定的URL地址接收传入的Webhook、生成签名及向艾克索拉Webhook服务器发送响应。

生成签名

接收Webhook时，应确保数据传输的安全性。为此，必须从Webhook数据生成一个签名并确保它与HTTP请求头中发送的签名匹配。

要生成签名：

1. 将请求正文中的JSON与项目密钥串联起来。
2. 对第一步中得到的字符串应用SHA-1加密散列函数。

向Webhook发送响应

要确认收到Webhook，您的服务器必须返回：

• 200、201或204 HTTP代码（成功响应时）。
• 带问题描述的400 HTTP代码（如未找到指定用户或传入的签名无效）。

如您的服务器发生临时问题，您的Webhook处理程序也可以返回5xx代码。

如果未收到对订单成功支付或订单取消Webhook的响应，或收到了包含5xx代码的响应，将根据以下规则重新发送Webhook：

• 间隔5分钟尝试2次
• 间隔15分钟尝试7次
• 间隔60分钟尝试10次

自首次尝试起，12小时内最多尝试发送Webhook20次。

如果未收到对支付Webhook的响应或收到了包含5xx代码的响应，也将尝试重新发送Webhook且重试的间隔逐渐拉长。12小时内最多尝试12次。

如果未收到对用户验证Webhook的响应或收到了包含400或5xx代码的响应，将不会重新发送用户验证Webhook。

该情况下会向用户显示一个错误，且不会发送支付和订单成功支付Webhook。