概览

如果艾克索拉侧发生了预先配置的事件，可通过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"
    }
}