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

事件示例：

• 用户与商品目录交互
• 付款或取消订单

当发生设定事件时，艾克索拉会通过Webhook通知您的系统。然后，您可以执行以下操作：

• 补充用户余额
• 进行退款
• 向用户帐户发放或减除新商品
• 开始提供订阅
• 怀疑欺诈行为时封禁用户

支付处理Webhook工作流示例：

支付处理Webhook

使用艾克索拉产品和解决方案时的Webhook设置：

产品/解决方案	必需/可选	Webhook的用途是什么
支付	必需	用户验证。 付款成功或退款时接收交易详情的信息。 将购买的商品记入用户帐户，及在订单取消时将商品减除。
游戏内商店	必需	用户验证。 付款成功或退款时接收交易详情的信息。 将购买的商品记入用户帐户，及在订单取消时将商品减除。
购买按钮	可选	对于游戏密钥销售，用户验证和商品记入不是必需。如果想接收有关事件的信息（例如付款或订单取消），可以连接webhook。 如果连接Webhook，则必须处理所有传入的必需Webhook。
订阅	可选	接收有关创建、更新或取消订阅的信息。您也可以通过API请求信息。
网页商城	可选	用于用户认证（如果使用通过用户ID进行身份认证）。您也可以使用通过艾克索拉登录管理器进行用户认证。
Digital Distribution Hub	可选	用户验证。 将艾克索拉侧的交易ID与您系统中的交易ID关联。 在订单中传输额外交易参数。 将购买的商品记入用户帐户，及在订单取消时将商品减除。 详细信息请参阅为Digital Distribution Hub设置Webhook的说明。

如果使用需要Webhook的产品和解决方案，请在您的发布商帐户中启用并测试Webhook并设置Webhook处理。当特定事件发生时，Webhook会按顺序发送。因此，如果您不处理其中一个Webhook，则不会发送后续Web hook。下面列出了必需Webhook的列表。

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

• 用户验证(user_validation) — 在支付过程的不同阶段发送，以确保用户已在游戏中注册。
• 支付(payment) — 在支付订单后发送，包含付款数据和交易详细信息。
• 订单支付成功(order_paid) — 支付Webhook已成功处理时发送并包含有关购买的商品和交易ID的信息。使用该We bhook中的数据向用户添加商品。
• 退款(refund) — 订单被取消后发送，包含取消的付款数据和交易详细信息。
• 订单取消(order_canceled) —退款Webhook已成功处理时发送，并包含有关所购商品的信息和已取消交易的ID。使用 该Webhook中的数据移除购买的商品。

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

要自动管理订阅计划，需要实现主要Webhook的处理：

• 用户验证(user_validation) — 在支付过程的不同阶段发送，以确保用户已在游戏中注册。
• 支付(payment) — 在支付订单后发送，包含付款数据和交易详细信息。
• 创建了订阅(create_subscription) — 支付Webhook已成功处理或用户购买了具有试用期的订阅时发送。它包含所购买的订阅 的详细信息和用户数据。使用该Webhook数据向用户添加订阅。
• 更新了订阅(update_subscription) — 续订或更改订阅以及支付Webhook已成功 处理后发送。它包含所购买的订阅的详细信息和用户数据。使用该Webhook数据来延长用户的订阅或更改订阅参数。
• 退款(refund) — 订单被取消后发送，包含取消的付款数据和交易详细信息。
• 取消了订阅(cancel_subscription) — 退款Webhook已成功处理或订阅因其他原因被取消时发送。它包含有关订阅和用户数据的 信息。使用该Webhook数据扣除用户购买的订阅。

要启用接收Webhook：

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

要禁用接收Webhook：

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

测试Webhook有助于确保己侧和艾克索拉侧的项目设置都正确。

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

Webhook名称	Webhook类型
用户验证	user_validation
支付	payment
订单取消	order_canceled
订单支付成功	order_paid

如果Webhook设置成功，Webhook 设置部分下方会显示一个Webhook测试部分。

！Webhook测试部分

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

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

要进行测试：

1. 在Webhook测试部分中，前往商店选项卡。
2. 在下拉菜单中，选择商品类型。如果所选类型的商品未在发布商帐户中设置，请单击：
   • 连接 – 如果未连接该类型商品的模块
   • 配置 – 如果之前连接过模块，但尚未完成设置
     单击该按钮后，您将被重定向到与所选商品类型相对应的发布商帐户部分。创建商品后，返回Webhook测试部分并继续下一步 。
3. 在艾克索拉订单ID字段中输入任意值。
4. 从下拉列表中选择商品的SKU并注明金额。您可以通过单击+并将它们添加到新行中来选择多个相同类型的商品。
5. 选择支付订单所用的货币。
6. 单击测试。

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

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

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

要进行测试：

1. 在测试部分，前往付款选项卡。
2. 填写必填字段：

   1. 用户ID — 测试时，您可以使用任意字母和数字的组合。
   2. 公共用户ID — 用户已知的ID，例如电子邮件或昵称。如果您的项目中的支付中心 > 设置 > 其他设置部分启用了公共用户ID，则会显示此字段。
   3. 货币 — 从下拉列表中选择一种货币。
   4. 艾克索拉发票ID — 艾克索拉侧的交易 ID。测试时，您可以使用任何数值。
   5. 金额 — 支付金额。测试时，您可以使用任何数值。
   6. 发票ID — 您游戏侧的交易 ID。测试时，您可以使用任意字母和数字的组合。它不是成功付款的必需参数，但您可以传递它以将己侧的交易ID与艾克索拉侧交易ID关联。
3. 单击测试Webhook。

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

对于每个Webhook，您需要配置处理两种情况：成功的情况和出现错误的情况。

！付款测试部分

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

开关	描述
显示保存的支付帐户的信息	有关保存的支付方式的信息在payment_account自定义对象中传递。
显示通过保存的支付方式进行的交易的信息	信息在Webhook的以下自定义参数中传递： saved_payment_method: 0 — 未使用保存的支付方式 1 — 进行当前付款时保存了支付方式 2 — 使用了之前保存的支付方式 payment_type: 1 — 一次性支付 2 — 定期支付
将订单对象添加到Webhook	有关订单的信息在支付Webhook的order对象中传递。
仅发送不含敏感数据的必要用户参数	Webhook中仅传递用户的以下信息： ID 国家/地区
发送自定义参数	自定义令牌参数的信息在webhook中传递。
显示银行卡BIN和后缀码	Webhook中传递以下银行卡号的信息： card_bin参数中的前6位数字 card_suffix中的后4位数字
显示银行卡品牌	用于付款的银行卡的品牌。例如，Mastercard或Visa。

在订阅选项卡中，您可以测试以下Webhook：

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

要进行测试：

1. 在测试部分，前往订阅选项卡。
2. 填写必填字段：

   1. 用户ID — 测试时，您可以使用任意字母和数字的组合。
   2. 艾克索拉发票ID — 艾克索拉侧的交易ID。测试时，您可以使用任何数值。
   3. 公共用户ID — 用户已知的ID，例如电子邮件或昵称。如果您的项目中的支付中心 > 设置 > 其他设置部分启用了公共用户ID，则会显示此字段。
   4. 货币 — 从下拉列表中选择一种货币。
   5. 计划ID — 订阅计划。从下拉列表中选择一个计划。
   6. 订阅产品 — 从下拉列表中选择产品（可选）。
   7. 金额 — 支付金额。测试时，您可以使用任何数值。
   8. 发票ID — 您游戏侧的交易 ID。测试时，您可以使用任意字母和数字的组合。它不是成功付款的必需参数，但您可以传递它以将己侧的交易ID与艾克索拉侧交易ID关联。
   9. 试用期。如要测试购买无试 用期的订阅或测试续订，请指定值0。
3. 单击测试Webhook。

在指定的URL中，您将收到包含所填数据的Webhook。每个Webhook的测试结果（成功场景和错误场景）都在测试Webhook按钮下方显示。

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

在应用程序侧，实现从以下IP地址接收Webhook：185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197。

限制：

• 应用程序的数据库中不应存在具有相同ID的多个成功交易。
• 如果Webhook侦听器收到的Webhook的ID已经存在于数据库中，则需返回之前处理该交易的结果。不建议向用户发放重复购买及在数据库中创建重复记录。

接收Webhook时，应保证数据传输的安全。为此，必须从Webhook数据生成签名，并验证它是否与HTTP请求标头中发送的签名匹配。要生成签名：

1. 连接请求正文中的JSON和项目的密钥。
2. 将SHA-1加密哈希函数应用于第一步中获得的字符串。

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

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

• 如果响应成功，返回200、201或204HTTP代码。
• 如果未找到指定的用户或传递了无效的签名，返回400 HTTP代码和问题描述。如果您的服务器出现临时问题，您的Webhook处理程序还可 以返回5xxHTTP 代码。

如果没有收到订单支付成功和订单取消Webhook的响应或者如果收到包含5xx代码的响应，则根据以下时间表重新发送Webhook：

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

自第一次尝试后12小时内最多可尝试20次发送Webhook。如果对于支付Webhook或退款Webhook未收到响应，或者如果收到带有5xx代码的响应，Webhook也 会以递增的时间间隔重新发送。 12小时内最多进行12次尝试。

如果没有收到用户验证Webhook的响应或收到代码为400或5xx的响应，将不重新发送用户验证Webhook。在这种情况下，会向用户显示错误，并且不发送支付和订单支付成功webhook。

HTTP代码400的错误代码：

代码	消息
INVALID_USER	无效用户
INVALID_PARAMETER	无效参数
INVALID_SIGNATURE	无效签名
INCORRECT_AMOUNT	金额不正确
INCORRECT_INVOICE	发票不正确

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook	通知类型	描述
用户验证	user_validation	发送以检查用户是否存在于游戏中。
用户搜索	user_search	发送以根据公共用户ID获取用户信息。
支付	payment	用户完成支付流程时发送。
退款	refund	出于某些原因需要取消支付时发送。
部分退款	partial_refund	出于某些原因需要部分取消支付时发送。
AFS拒绝交易	afs_reject	交易在AFS检查过程中被拒绝时发送。
AFS更新的拦截列表	afs_black_list	AFS拦截列表发生更新时发送。
创建了订阅	create_subscription	用户创建订阅时发送。
更新了订阅	update_subscription	订阅发生续订或更改时发送。
取消了订阅	cancel_subscription	取消订阅时发送。
非续订订阅	non_renewal_subscription	状态设置为非续订时发送。
添加支付账户	payment_account_add	当用户添加或保存支付帐户时发送。
删除支付账户	payment_account_remove	用户从已保存的帐户中删除了支付帐户时发送。
Web商店中的用户验证	-	从Web商店网站发送以检查游戏中是否存在该用户。
合作伙伴侧目录个性化	partner_side_catalog	用户与商店交互时发送。
订单支付成功	order_paid	订单付款后发送。
订单取消	order_canceled	订单取消时发送。
争议	dispute	当提出新争议时发送。