概览

如果艾克索拉侧发生了预先配置的事件，可通过Webhook收到即时通知。您可以使用Webhook来自动化应用程序的后端和补充功能。

可收到通知的事件示例：

支付，包括购买虚拟货币和物品
定期付款和订阅操作
退款

当配置的事件发生时，艾克索拉会通过webhook通知您的系统。例如，您可以在收到webhook后执行以下操作：

添加到用户的余额
为用户解锁新物品
开始订阅服务
在检测到欺诈后拦截用户

以下是支付处理Webhook工作原理的示例：

支付处理Webhook

设置服务器侧

必须应用以下设置才能使webhook正常工作：

监听以下IP地址的webhook：185.30.20.0/24、185.30.21.0/24、185.30.23.0/24。
应用程序数据库不得包含ID相同的两个成功交易。

注意

如果收到的Webhook的交易ID在数据库中已存在，则监听器应返回该次交易的上次处理结果。不推荐向用户重复扣款或在数据库中创建重复记录。

创建的签名必须与HTTP头中传递的签名相匹配。
如果出现错误，返回代码400（例如，缺少必填参数或扣款失败时）。对于服务器的临时错误，请使用代码 500。

注：

艾克索拉API接受传统HTTP响应代码指示请求是成功还是失败。代码204指示处理成功。

由于网络连接并不总是100%可靠，因此Webhook可能会丢失或延迟。为解决此问题，艾克索拉会重新发送失败的Webhook，直到侦听器收到它们。初始Webhoo k发送之后12小时内会重新发送Webhook，直到侦听器确认接收。最大重试次数为12次。

注：

尽管网络连接可能导致出错，但最有可能导致丢失、延迟或重复Webhook的原因是监听器本身存在逻辑问题。

请求签名

数字签名可实现安全的数据传输。要生成签名：

将请求的JSON正文与项目的密钥连接起来。
对结果字符串应用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"
      }
    }'

错误

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列表

注：

通知类型在notification_type参数中发送。

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`	状态设置为非续订时发送。
获取游戏密钥	Buy Button	`get_pincode`	在艾克索拉API需要获取游戏密钥时发送。
用户余额：手动更新	游戏内商店	`user_balance_operation`	手动更改用户余额时发送。操作类型——`internal`。
用户余额：付款	游戏内商店	`user_balance_operation`	当用户付款时发送。操作类型——`payment`。
用户余额：退款	游戏内商店	`user_balance_operation`	当用户取消付款时发送。操作类型——`cancellation`。
用户余额：兑换优惠券	游戏内商店	`user_balance_operation`	当用户在游戏中兑换优惠券以接收虚拟物品或虚拟货币时发送。操作类型——`coupon`。
用户余额：购买	游戏内商店	`user_balance_operation`	当用户在游戏中进行购买时发送。操作类型——`inGamePurchase`。
激活密钥	Buy Button	`redeem_key`	用户激活密钥时发送。
添加支付账户	支付中心	`payment_account_add`	当用户添加或保存支付帐户时发送。
删除支付账户	支付中心	`payment_account_remove`	用户从已保存的帐户中删除了支付帐户时发送。
Web商店中的用户验证	Web商店	`-`	从Web商店网站发送以检查游戏中是否存在该用户。
提现交易处理中	提现	`-`	通知提现交易已创建并正在处理时发送。
提现交易完成	提现	`-`	通知提现交易已成功完成时发送。
合作伙伴侧目录个性化	游戏内商店	`partner_side_catalog`	用户与商店交互时发送。
订单支付成功	游戏内商店	`order_paid`	订单付款后发送。
订单取消	游戏内商店	`order_canceled`	订单取消时发送。