Webhook是系统中发生的事件的通知。当特定事件发生时,艾克索拉会向您的应用程序发送HTTP请求,其中会传输事件数据。它通常是JSON格式的POST请求。
事件示例:
当发生设定事件时,艾克索拉会通过Webhook通知您的系统。然后,您可以执行以下操作:
支付处理Webhook工作流示例:
使用艾克索拉产品和解决方案时的Webhook设置:
产品/解决方案 | 必需/可选 | Webhook的用途是什么 |
---|---|---|
支付 | 必需 |
|
游戏内商店 | 必需 |
|
购买按钮 | 可选 | 对于游戏密钥销售,用户验证和商品记入不是必需。如果想接收有关事件的信息(例如付款或订单取消),可以连接webhook。 如果连接Webhook,则必须处理所有传入的必需Webhook。 |
订阅 | 可选 | 接收有关创建、更新或取消订阅的信息。您也可以通过API请求信息。 |
网页商城 | 可选 | 用于用户认证(如果使用通过用户ID进行身份认证)。您也可以使用通过艾克索拉登录管理器进行用户认证。 |
Digital Distribution Hub | 可选 |
|
如果使用需要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:
https://example.com
。您还可以指定在测试Web
hook的工具中找到的URL。注:
请使用HTTPS协议传输数据,不支持HTTP协议。
注:
要测试Webhook,可以选择任何专用网站(例如webhook.site)或平台(例如ngrok)。
注:
无法同时将Webhook发送到不同的URL。您可以在发布商帐户中执行的操作是先指定一个用于测试的URL,然后将其替换为真实的URL。
要禁用接收Webhook:
测试Webhook有助于确保己侧和艾克索拉侧的项目设置都正确。
您可以测试以下Webhook的接收:
Webhook名称 | Webhook类型 |
---|---|
用户验证 | user_validation |
支付 | payment |
订单取消 | order_canceled |
订单支付成功 | order_paid |
如果Webhook设置成功,Webhook 设置部分下方会显示一个Webhook测试部分。
注:
如果测试部分出现测试未通过的警告,请在您的Webhook侦听器中检查Webhook响应设置。测试结果中指出了测试错误的原因。
示例:
您使用专门的网站webhook.site来进行测试。
测试对无效签名的响应部分显示了一个错误。
发生这种情况是因为艾克索拉发送了带有错误签名的Webhook,并期望您的处理程序用一个指出INVALID_SIGNATURE
错误代码的4xx
HTTP代码进行响应。
webhook.site对所有Webhook的响应中都发送一个200
HTTP代码,包括签名不正确的Webhook。由于无法获取预期的4xx
HTTP代码,因此测试结果报错。
在商店选项卡中,您可以测试以下Webhook:
要进行测试:
包含指定数据的订单支付成功和订单取消Webhook将发送到所提供的URL。测试每个Webhook类型的结果在测试Webhook按钮下方显示 。
在付款选项卡中,您可以测试以下Webhook:
要进行测试:
在指定的URL中,您将收到包含所填数据的Webhook。每个Webhook的测试结果(成功场景和错误场景)都在测试Webhook按钮下方显示。如果 您的项目中启用了公共用户ID,您还将看到用户搜索检查的结果。
对于每个Webhook,您需要配置处理两种情况:成功的情况和出现错误的情况。
将URL保存在Webhook服务器字段时可以看到高级设置部分,您可以在其中授予在Webhook中接收详细信息的权限。为此,请将相应的 开关设置为开。在每个权限的所在行中,您可以看到受该设置影响的Webhook列表。
开关 | 描述 |
---|---|
显示保存的支付帐户的信息 | 有关保存的支付方式的信息在payment_account 自定义对象中传递。 |
显示通过保存的支付方式进行的交易的信息 | 信息在Webhook的以下自定义参数中传递:
|
将订单对象添加到Webhook | 有关订单的信息在支付Webhook的order 对象中传递。 |
仅发送不含敏感数据的必要用户参数 | Webhook中仅传递用户的以下信息:
|
发送自定义参数 | 自定义令牌参数的信息在webhook中传递。 |
显示银行卡BIN和后缀码 | Webhook中传递以下银行卡号的信息:
|
显示银行卡品牌 | 用于付款的银行卡的品牌。例如,Mastercard或Visa。 |
在订阅选项卡中,您可以测试以下Webhook:
注:
要测试Webhook,您应该在发布商帐户>订阅>订阅计划部分中至少有一个已创建的订阅计划。
要进行测试:
0
。在指定的URL中,您将收到包含所填数据的Webhook。每个Webhook的测试结果(成功场景和错误场景)都在测试Webhook按钮下方显示。
Webhook侦听器是一个程序代码,允许在指定URL地址接收传入的Webhook、生成签名以及发送响应到艾克索拉Webhook服务器。
注:
您可以使用Pay Station PHP SDK 库,它包含用于处理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
。
限制:
接收Webhook时,应保证数据传输的安全。为此,必须从Webhook数据生成签名,并验证它是否与HTTP请求标头中发送的签名匹配。要生成签名:
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
或204
HTTP代码。400
HTTP代码和问题描述。如果您的服务器出现临时问题,您的Webhook处理程序还可
以返回5xx
HTTP 代码。如果没有收到订单支付成功和订单取消Webhook的响应或者如果收到包含5xx
代码的响应,则根据以下时间表重新发送Webhook:
自第一次尝试后12小时内最多可尝试20次发送Webhook。如果对于支付Webhook或退款Webhook未收到响应,或者如果收到带有5xx
代码的响应,Webhook也
会以递增的时间间隔重新发送。 12小时内最多进行12次尝试。
注:
如果退款是由艾克索拉发起的,并且收到带有`5xx` HTTP代码的退款Webhook响应,付款仍会被退还。
如果没有收到用户验证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"
}
}
注:
通知类型在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 |
状态设置为非续订时发送。 |
添加支付账户 | payment_account_add |
当用户添加或保存支付帐户时发送。 |
删除支付账户 | payment_account_remove |
用户从已保存的帐户中删除了支付帐户时发送。 |
Web商店中的用户验证 | - |
从Web商店网站发送以检查游戏中是否存在该用户。 |
合作伙伴侧目录个性化 | partner_side_catalog |
用户与商店交互时发送。 |
订单支付成功 | order_paid |
订单付款后发送。 |
订单取消 | order_canceled |
订单取消时发送。 |
争议 | dispute |
当提出新争议时发送。 |