商品添加 Webhook

阿哈利姆提供了一个集中式 Webhook，它会根据玩家在游戏枢纽中的活动，通知您的游戏向玩家账户添加商品。 当玩家执行需要添加商品的操作时，该 Webhook 就会被触发。 本指南详细介绍了该 Webhook 的功能和设置方法。

此 Webhook 在以下情况下触发：

• 玩家在游戏枢纽中进行购买
• 玩家在游戏枢纽中兑换免费商品码
• 玩家领取每日奖励或玩家激励计划奖励

每个通知都包含一个 reason 字段，说明添加商品的原因。

要求

要使用阿哈利姆的 item.add Webhook，请按照以下要求配置您的 Webhook 服务器：

• HTTPS 端点，可接收 POST Webhook 请求。
• 监听由阿哈利姆生成并 签名 的事件。
• 处理 Webhook 负载中包含的 idempotency_key，以防止重复处理 Webhook。
• 将指定商品添加到玩家账户。
• 使用 2xx 状态码表示成功处理，使用 4xx 或 5xx 状态码表示拒绝或错误。

配置步骤

以下是处理阿哈利姆 Webhook 的端点函数模板，用于通知您的游戏添加商品：

• Python
• Ruby
• Node.js
• Go

import fastapi, hashlib, hmac, json, typing 

app = fastapi.FastAPI()

@app.post("/webhook")
async def webhook(request: fastapi.Request) -> dict[str, typing.Any]:
    secret_key = "<YOUR_S2S_KEY>"  # 请替换为您的实际 Webhook Secret Key

    raw_payload = await request.body()
    payload = raw_payload.decode()
    timestamp = request.headers["x-aghanim-signature-timestamp"]
    received_signature = request.headers["x-aghanim-signature"]

    if not verify_signature(secret_key, payload, timestamp, received_signature):
        raise fastapi.HTTPException(status_code=403, detail="Invalid signature")

    data = json.loads(payload)
    event_type = data["event_type"]
    event_data = data["event_data"]

    if event_type == "item.add":
        add_item(event_data)
        return {"status": "ok"}

    raise fastapi.HTTPException(status_code=400, detail="Unknown event type")

def verify_signature(secret_key: str, payload: str, timestamp: str, received_signature: str) -> bool:
    signature_data = f"{timestamp}.{payload}"
    computed_hash = hmac.new(secret_key.encode(), signature_data.encode(), hashlib.sha256)
    computed_signature = computed_hash.hexdigest()
    return hmac.compare_digest(computed_signature, received_signature)

def add_item(event_data: dict[str, typing.Any]) -> None:
    # 用于处理事件和添加商品的示例占位代码。
    # 在实际应用中，此函数将与您的数据库或库存管理系统进行交互。
    player_id = event_data["player_id"]
    for item in event_data["items"]:
      sku = event_data["sku"]
      print(f"Item {sku} have been credited to player's {player_id} account.")

require 'sinatra'
require 'json'
require 'openssl'

post '/webhook' do
  secret_key = "<YOUR_S2S_KEY>"  # 请替换为您的实际 Webhook Secret Key

  payload = request.body.read
  timestamp = request.env["HTTP_X_AGHANIM_SIGNATURE_TIMESTAMP"]
  received_signature = request.env["HTTP_X_AGHANIM_SIGNATURE"]

  unless verify_signature(secret_key, payload, timestamp, received_signature)
    halt 403, "Invalid signature"
  end

  data = JSON.parse(payload)
  event_type = data["event_type"]
  event_data = data["event_data"]

  if event_type == "item.add"
    add_item(event_data)
    return { status: "ok" }.to_json
  end

  halt 400, "Unknown event type"
end

def verify_signature(secret_key, payload, timestamp, received_signature)
  signature_data = "#{timestamp}.#{payload}"
  computed_signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, signature_data)
  OpenSSL.secure_compare(computed_signature, received_signature)
end

def add_item(event_data)
  # 用于处理事件和添加商品的示例占位代码。
  # 在实际应用中，此函数将与您的数据库或库存管理系统进行交互。
  player_id = event_data["player_id"]
  for item in event_data["items"] do
    sku = item["sku"]
    puts "Item #{sku} has been credited to player's #{player_id} account."
  end
end

const express = require('express');
const crypto = require('crypto');

const app = express();

app.post('/webhook', express.raw({ type: "*/*" }), async (req, res) => {
  const secretKey = '<YOUR_S2S_KEY>'; // 请替换为您的实际 Webhook Secret Key

  const rawPayload = req.body;
  const timestamp = req.headers['x-aghanim-signature-timestamp'];
  const receivedSignature = req.headers['x-aghanim-signature'];

  if (!verifySignature(secretKey, rawPayload, timestamp, receivedSignature)) {
    return res.status(403).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  const { event_type, event_data } = payload;

  if (event_type === 'item.add') {
    addItem(event_data);
    return res.json({ status: 'ok' });
  }

  return res.status(400).send('Unknown event type');
});

function verifySignature(secretKey, payload, timestamp, receivedSignature) {
  const signatureData = `${timestamp}.${payload}`;
  const computedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(signatureData)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(receivedSignature));
}

function addItem(event_data) {
  // 用于处理事件和添加商品的示例占位代码。
  // 在实际应用中，此函数将与您的数据库或库存管理系统进行交互。
  const playerId = event_data.player_id;
  for (const item of event_data.items) {
    const sku = item.sku;
    console.log(`Item ${item.sku} has been credited to player's ${playerId} account.`);
 }
}

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  secretKey := "<YOUR_S2S_KEY>"  // 请替换为您的实际 Webhook Secret Key

  rawPayload, _ := ioutil.ReadAll(r.Body)
  payload := string(rawPayload)
  timestamp := r.Header.Get("X-Aghanim-Signature-Timestamp")
  receivedSignature := r.Header.Get("X-Aghanim-Signature")

  if !verifySignature(secretKey, payload, timestamp, receivedSignature) {
    http.Error(w, "Invalid signature", http.StatusForbidden)
    return
  }

  var data map[string]interface{}
  if err := json.Unmarshal(rawPayload, &data); err != nil {
    http.Error(w, "Invalid payload", http.StatusBadRequest)
    return
  }

  eventType := data["event_type"].(string)
  eventData := data["event_data"].(map[string]interface{})

  if eventType == "item.add" {
    addItem(eventData)
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
    return
  }

  http.Error(w, "Unknown event type", http.StatusBadRequest)
}

func verifySignature(secretKey, payload, timestamp, receivedSignature string) bool {
  signatureData := fmt.Sprintf("%s.%s", timestamp, payload)
  mac := hmac.New(sha256.New, []byte(secretKey))
  mac.Write([]byte(signatureData))
  computedSignature := hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(computedSignature), []byte(receivedSignature))
}

func addItem(eventData map[string]interface{}) {
  // 用于处理事件和添加商品的示例占位代码。
  // 在实际应用中，此函数将与您的数据库或库存管理系统进行交互。
  playerID := eventData["player_id"].(string)
  items := eventData["items"].([]interface{})
  for _, item := range items {
    itemMap := item.(map[string]interface{})
    sku := itemMap["sku"].(string)
    fmt.Printf("Item %s has been credited to player's %s account.\\n", sku, playerID)
  }
}

当您的函数准备就绪后：

1. 部署您的端点使其可访问。
2. 在Aghanim账户中注册您的端点 → 游戏 → Webhooks → 新建 Webhook 通过选择相应的事件类型。

或者，您也可以使用 Create Webhook API 方法在阿哈利姆中注册您的端点。

Request Schema

下面是一个 item.add Webhook 请求示例：

HTTP

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "item.add",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "水晶",
        "description": "拿下这款豪华水晶宝藏，主宰游戏世界。",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null,
        "fallback_item": null
      }
    ],
    "reason": "订单支付 ord_eCacAulggpY"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "order.paid",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": {
    "order": {
      "id": "ord_eCacAulggpY",
      "amount": 9499,
      "country": "US",
      "currency": "USD",
      "revenue_usd": 9499,
      "fees": {
        "payment_system_fee_usd": 2.85,
        "aghanim_fee_usd": 14.25,
        "taxes_usd": 7.65
      },
      "receipt_number": "1234567890",
      "status": "paid",
      "created_at": 1725548450,
      "paid_at": 1725548460,
      "coupons": [
        {
          "id": "cpn_eGGhmqBXdWu",
          "code": "SH65",
          "name": "Shekhar",
          "type": "non_benefit",
          "discount_percent": null,
          "bonus_percent": null,
          "bonus_fixed": null
        }
      ],
      "creator": null
    }
  },
  "game_id": "gm_exTAyxPsVwh"
}
            

cURL

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "item.add",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "items": [
          {
            "id": "itm_exTBZQmIlDz",
            "name": "水晶",
            "description": "拿下这款豪华水晶宝藏，主宰游戏世界。",
            "sku": "crystals",
            "quantity": 480000,
            "price": 9499,
            "price_decimal": 94.99,
            "currency": "USD",
            "type": "item",
            "nested_items": null,
            "fallback_item": null
          }
        ],
        "reason": "订单支付 ord_eCacAulggpY"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "order.paid",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": {
        "order": {
          "id": "ord_eCacAulggpY",
          "amount": 9499,
          "country": "US",
          "currency": "USD",
          "revenue_usd": 9499,
          "fees": {
            "payment_system_fee_usd": 2.85,
            "aghanim_fee_usd": 14.25,
            "taxes_usd": 7.65
          },
          "receipt_number": "1234567890",
          "status": "paid",
          "created_at": 1725548450,
          "paid_at": 1725548460,
          "coupons": [
            {
              "id": "cpn_eGGhmqBXdWu",
              "code": "SH65",
              "name": "Shekhar",
              "type": "non_benefit",
              "discount_percent": null,
              "bonus_percent": null,
              "bonus_fixed": null
            }
          ],
          "creator": null
        }
      },
      "game_id": "gm_exTAyxPsVwh"
    }'
            

事件 Schema

键名	类型	描述
event_id	string	阿哈利姆生成的唯一事件标识符。
game_id	string	您的游戏在阿哈利姆中的唯一标识符。
event_type	string	事件的类型， item.add 在此情境下。
event_time	number	以 Unix 时间戳表示的事件发生日期。
event_data	EventData	包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_key	string	即使出现重试情况，也能确保 Webhook 操作只执行一次。
request_id	string|null	如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
sandbox	boolean	标识事件是否来自沙盒测试环境的指示器。
trigger	string|null	The trigger that caused the event to be sent.
transaction_id	string	阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
context	EventContext|null	事件的相关上下文信息。

EventContext Schema

键名	类型	描述
order	OrderContext|null	与事件相关的订单信息（如果适用）。
player	PlayerContext|null	（可选）玩家信息。如需启用，请在webhook设置中选择“添加玩家上下文”。

EventData Schema

键名	类型	描述
player_id	string	用于玩家身份验证的唯一 玩家 ID。
items	Item[]	要添加到玩家账户的商品数组。
reason	string	触发 Webhook 的可读原因。 示例：订单支付 ord_eCacAulggpY。

触发值

值	描述
coupon.redeemed	当免费物品的优惠券被兑换。
order.paid	当购买成功完成。
hub.free_item_claim	当玩家在商店领取免费物品。
hub.daily_reward_claim	当玩家收取每日奖励计划的奖励。
hub.loyalty_claim	当玩家领取忠诚计划奖励。
hub.progression_reward_claimed	当玩家领取进度奖励。
hub.rolling_offer_claimed	当玩家在滚动优惠中领取奖励。
hub.pick_one_offer_claimed	当玩家在选择一项优惠中领取奖励。
hub.lootbox.open	当玩家购买后打开战利品箱。
liveops.execute_action	当执行 LiveOps 操作时。
test	在 Dashboard 中使用 "Send test event" 时。

Item Schema

Key	Type	描述
id	string	阿哈利姆生成的商品唯一标识符。
name	string	商品名称。
description	string|null	商品描述。
sku	string	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
quantity	number	商品数量。
price	number|null	商品价格使用 最小货币单位。若商品为免费提供，则此字段值为 null.
price_decimal	number|null	商品价格（以十进制单位表示）。若商品为免费提供，则此字段值为 null。
currency	string|null	商品价格 货币单位。若商品为免费提供，则此字段值为 null.
type	string	商品类型，可选值包括： item, bundle.
nested_items	NestedItem[]|null	礼包内包含的所有单独商品组成的数组。
fallback_item	Item|null	如果无法向玩家发放主要商品，系统将提供的备选商品。
source	string	Identifies why the item is being delivered. Possible values: order, bonus, bundle, coupon, lootbox, free_item, liveops, daily_reward, loyalty_reward, progression_program, rolling_offer, pick_one_offer.
metadata	object|null	Custom key-value pairs for the item to support additional logic on your end.

商品类型 bundle 可以包含多个嵌套商品。
您可以选择处理礼包的通用 SKU，也可以单独处理每个嵌套商品。

NestedItem Schema

键名	类型	描述
id	string	阿哈利姆生成的商品唯一标识符。
name	string	商品名称。
description	string|null	商品描述。
sku	string	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
quantity	number	商品数量。
fallback_item	Item|null	如果无法向玩家发放主要商品，系统将提供的备选商品。
metadata	object|null	Custom key-value pairs for the item to support additional logic on your end.

OrderContext Schema

键名	类型	描述
id	string	阿哈利姆生成的唯一订单标识符。
receipt_number	string	在玩家的收据中显示的收据号码。
amount	number	订单金额（以当地货币表示），在 最小货币单位.
amount_before_discount	number	折扣前订单金额（以当地货币表示），在 最小货币单位.
payment_amount	number|null	Final amount charged to the customer in local currency, including taxes, in major currency units.
currency	string	订单使用的三字母货币代码（遵循 ISO 4217 标准）。
payment_method	string	使用的支付方式，例如 card, apple_pay, google_pay, paypal.
country	string	支付方式的国家的二位字母代码（遵循 ISO 3166-1 alpha-2 标准）。
payment_amount_usd	number|null	支付金额使用预估汇率换算成美元（例如，对于 $112.50 为 112.50）。最终金额在与支付提供商对账后确认，通常在下个月的10号前完成。
revenue_usd	number|null	预期净收入会按预计汇率及支付手续费折算为美元美分。实际金额需与支付平台核账确认，一般于次月 10 日前完成结算。
fees	Fees|null	有关税费的信息。实际金额需与支付平台核对确认，一般于次月10日前完成结算。
status	string	订单状态，可选值包括： created, captured, paid, canceled, refunded, refund_requested.
sales_channel	string	指示销售渠道。可以是： game_hub, checkout, android_sdk, checkout_link.
eligible_for_reward_points	number|null	该订单能够获得的奖励积分数量。
eligible_for_loyalty_points	number|null	该订单能够获得的用户积分数量。
coupons	Coupon[]|null	The list of coupons (codes) redeemed at checkout when purchasing items or bundles. Coupons can grant a discount or a bonus. See The Coupon schema below.
created_at	number	以 Unix 时间戳表示的订单创建日期。
paid_at	number|null	以 Unix 时间戳表示的订单支付日期。
creator	Creator|null	Information about creator associated with the order.
metadata	object|null	自定义的键值对数据对象，用于存储与订单相关的额外信息。
rewards	OrderRewards|null	Rewards associated with the order, such as virtual currency granted on top of the purchased items.

费用数据 Schema

键名	类型	描述
payment_system_fee_usd	number|null	支付处理费用（美分）。
aghanim_fee_usd	number|null	阿哈利姆服务费（美分）。
taxes_usd	number|null	税费（美分）。
tax_country	string|null	Two-letter country code (ISO 3166-1 alpha-2) used to determine the tax rate applied to the order.
tax_percent	number|null	Tax rate applied to the order, expressed as a percentage (e.g. 20.5 for 20.5%).

The OrderRewards schema

键名	类型	描述
available	VirtualCurrencyReward[]	The list of virtual currency rewards available for the order.

The VirtualCurrencyReward schema

键名	类型	描述
type	string	The type of reward. Always virtual_currency.
name	string|null	The name of the virtual currency.
virtual_currency_id	string	Unique ID of the virtual currency generated by Aghanim.
amount	number	The amount of virtual currency to be granted to the player.
sku	string	SKU of the virtual currency matching on both the game and Aghanim sides.

The Coupon schema

键名	类型	描述
id	string	Unique coupon ID generated by Aghanim.
code	string	The coupon code redeemed by the player at checkout (e.g. WHATSAPP20, SNAG15). This is the value to use for attribution and analytics.
name	string	The internal name of the coupon.
type	string	The type of the coupon. Possible values: bonus, discount, free_item, vc, non_benefit, discount_fixed, discount_reward_point.
discount_percent	integer|null	Discount percent for discount coupons.
bonus_percent	integer|null	Bonus percent for bonus coupons.
bonus_fixed	integer|null	Fixed bonus quantity for bonus coupons.

创作者 Schema

键名	类型	描述
name	string	创作者的名称。
payout_decimal_usd	number	创作者的支付金额（美元，主要单位）。

PlayerContext Schema

键名	类型	描述
player_id	string|null	唯一的 用于玩家身份验证的玩家标识符.
player	object|null	使用复合授权时的玩家ID组件。
attributes	Attributes	阿哈利姆需要的基本玩家属性。
custom_attributes	CustomAttributes	自定义玩家属性。

可选：拒绝购买并自动退款

在某些情况下，您的游戏服务器可能需要在支付处理后拒绝购买，例如当促销已过期或玩家不符合购买要求时。 阿哈利姆支持自动退款处理这些情况。

要拒绝购买，请返回 400 状态码：

{
 "status": "error",
 "code": "declined",
 "message": "购买被拒绝：促销已过期"
}

信息

自动退款必须由阿哈利姆团队进行配置。 请 联系我们的集成团队 以启用针对 code="declined" 的自动退款。

有关实施自动退款的详细信息，包括错误代码，请参阅自动支付退款。

需要技术支持？
联系我们的集成技术团队： [email protected]