设置Webhook

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

事件示例

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

Webhook列表

对于游戏密钥销售,无需进行用户验证和帐户中物品添加。如果您想接收付款或订单取消等事件的相关信息,可以连接Webhook。

如果连接了Webhook,请务必处理所有传入的必需Webhook。

注:

艾克索拉侧设置了两种接收网站上的商品购买和退款Webhook的方式——付款及交易数据信息和所购商品信息可以分开发送,也可以合并到一个Webhook中。

了解更多关于Webhook接收方式的信息

在合并Webhook中接收信息:

如果您在2025年1月22日之后在发布商帐户中注册,您将在订单支付成功(order_paid)和订单取消(order_canceled) Webhook中接收所有信息。在这种情况下,无需处理支付(payment)和退款(refund) Webhook。

在单独Webhook中接收信息:

如果您在2025年1月22日或之前在发布商帐户中注册,您将接收以下Webhook:

您需要处理所有传入的Webhook。

如需切换到接收合并Webhook的新方式,请联系您的客户成功经理或发送邮件至csm@xsolla.com

要实现游戏内商店和支付管理的完整功能,必须实现对主要Webhook的处理:

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

注:
要接收真实付款,只需签署许可协议并实现以下Webhook的处理:
注:
您可以使用PlayFab集成来接收付款和订单取消信息,而不必使用Webhook。

在发布商帐户中设置Webhook

要启用Webhook接收:

  1. 发布商帐户中打开您的项目。
  2. 在侧边栏中单击项目设置,然后前往Webhooks选项卡。
  3. Webhook服务器字段中指定要接收Webhook的服务器URL,格式为https://example.com。您也可以指定在工具中找到的URL来用于测试。

注意
请使用HTTPS协议传输数据,不支持HTTP协议。
  1. 默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥,请点击刷新图标。
  2. 单击启用Webhook

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

注:
要测试Webhook,您可以选择任意专门网站(如webhook.site)或平台(如ngrok)。
注意
不能同时向不同URL发送Webhook。您可以先在发布商帐户中指定一个用于测试的URL,后续再替换为真实的URL。
要禁用Webhook接收:
  1. 发布商帐户中打开您的项目。
  2. 在侧边栏中单击项目设置,然后前往Webhooks选项卡。
  3. 单击禁用Webhook

在发布商帐户中测试Webhook

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

发布商帐户中的测试部分会根据Webhook接收方式不同而有所不同。

下方介绍了合并Webhook场景的测试流程。 在付款和商店选项卡中,您可以测试以下Webhook:

要进行测试:

  1. 在Webhook测试部分,前往付款和商店选项卡。
  2. 在下拉菜单中选择游戏密钥。如未在发布商帐户中设置该游戏密钥套餐,会显示以下按钮之一:
    • 连接 – 如未连接游戏密钥模块
    • 配置 – 如之前已连接了该模块但未完成设置
  3. 填写必填字段:
    1. 艾克索拉订单ID字段中输入任意值。
    2. 从下拉列表中选择游戏密钥套餐。
    3. 指定游戏发布平台。
    4. 用户ID — 测试阶段可使用任意字母数字组合。
    5. 公共用户ID — 对用户显示的ID,例如邮箱或昵称。仅当在支付中心 > 设置部分为项目启用了公共用户ID时才会显示此字段。
    6. 艾克索拉发票ID — 艾克索拉侧的交易ID。测试阶段可使用任意数值。
    7. 发票ID — 游戏侧的交易ID。测试阶段可使用任意字母数字组合。它不是成功支付的必需参数,但可传入该参数来将己侧交易ID与艾克索拉侧交易ID关联起来。
    8. 数量 — 支付金额。测试阶段可使用任意数值。
    9. 货币 — 从下拉列表中选择一个货币。
  4. 单击测试Webhook
包含所指定数据的用户验证订单支付成功订单取消Webhook将发送到提供的URL。各Webhook类型的测试结果在测试按钮下方显示。 如果项目启用了公共用户ID,还将看到用户搜索检查的结果。

对于每个Webhook,均需要配置对两种场景(成功和出错)的处理。

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

Webhook监听器

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

生成签名

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

要生成签名:

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

向Webhook发送响应

要确认收到Webhook,您的服务器必须返回:

  • 200201204 HTTP代码(成功响应时)。
  • 问题描述400 HTTP代码(如未找到指定用户或传入的签名无效)。

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

如果艾克索拉服务器未收到对订单支付成功订单取消Webhook的响应,或收到了包含5xx代码的响应,将根据以下规则重新发送Webhook:

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

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

如果艾克索拉服务器未收到支付Webhook或退款Webhook的响应,或收到5xx代码的响应,也将尝试重新发送Webhook且重试的间隔逐渐拉长。12小时内最多尝试12次。

如果艾克索拉服务器未收到用户验证Webhook的响应,或收到4005xx代码的响应,将不会重新发送用户验证Webhook。

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

注:
Webhook的完整列表和机制以及详细的处理示例见Webhook文档
本文对您的有帮助吗?
谢谢!
我们还有其他可改进之处吗? 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈!
我们会查看您的留言并运用它改进用户体验。
上次更新时间: 2025年1月23日

发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。

报告问题
我们非常重视内容质量。您的反馈将帮助我们做得更好。
请留下邮箱以便我们后续跟进
感谢您的反馈!