商品添加 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
from fastapi.responses import JSONResponse

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 = item["sku"]
      print(f"Item {sku} has 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 方法在阿哈利姆中注册您的端点。

触发值

值	描述
coupon.redeemed	当免费物品的优惠券被兑换。
order.paid	当购买成功完成。
hub.purchase	当玩家完成在游戏枢纽中开始的购买。
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	当玩家购买后打开战利品箱。
checkout.purchase	当玩家在结账页面完成购买。
liveops.execute_action	当执行 LiveOps 操作时。
test	在 Dashboard 中使用 "Send test event" 时。

请参阅完整的事件与触发器对照表，了解 item.add 与其他事件类型的关系。

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,
        "source": "order"
      }
    ],
    "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",
      "receipt_number": "1234567890",
      "amount": 9499,
      "amount_before_discount": 9499,
      "payment_amount": 94.99,
      "payment_currency": "USD",
      "currency": "USD",
      "payment_method": "card",
      "country": "US",
      "payment_amount_usd": 94.99,
      "revenue_usd": 9499,
      "fees": {
        "payment_system_fee_usd": 2.85,
        "aghanim_fee_usd": 14.25,
        "taxes_usd": 7.65,
        "tax_country": "US",
        "tax_percent": null
      },
      "status": "paid",
      "sales_channel": "game_hub",
      "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,
            "source": "order"
          }
        ],
        "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",
          "receipt_number": "1234567890",
          "amount": 9499,
          "amount_before_discount": 9499,
          "payment_amount": 94.99,
          "payment_currency": "USD",
          "currency": "USD",
          "payment_method": "card",
          "country": "US",
          "payment_amount_usd": 94.99,
          "revenue_usd": 9499,
          "fees": {
            "payment_system_fee_usd": 2.85,
            "aghanim_fee_usd": 14.25,
            "taxes_usd": 7.65,
            "tax_country": "US",
            "tax_percent": null
          },
          "status": "paid",
          "sales_channel": "game_hub",
          "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	触发该事件发送的触发器。
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。

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	标识该商品被发放的原因，可选值包括： order, bonus, bundle, coupon, lootbox, free_item, liveops, daily_reward, loyalty_reward, progression_program, rolling_offer, pick_one_offer.
metadata	object|null	该商品的自定义键值对，用于支持您端的额外逻辑。

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

NestedItem Schema

键名	类型	描述
id	string	阿哈利姆生成的商品唯一标识符。
name	string	商品名称。
description	string|null	商品描述。
sku	string	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
quantity	number	商品数量。
fallback_item	Item|null	如果无法向玩家发放主要商品，系统将提供的备选商品。
metadata	object|null	该商品的自定义键值对，用于支持您端的额外逻辑。

订单货币与支付货币

一个订单包含两组货币/金额，二者可能不同：

• currency + amount — 用户在结账时看到的内容（订单货币及其金额）。
• payment_currency + payment_amount — 支付服务商实际收取的内容。

当某笔交易不支持订单货币时，二者会不同：金额会被转换为该国家/地区支付方式默认使用的货币。例如，塞尔维亚的玩家在结账时看到以 RSD 计价，但该笔交易不支持 RSD，因此支付会被转换并以 EUR 收取。结果是 currency = RSD、amount 以 RSD 计，而 payment_currency = EUR、payment_amount 以 EUR 计。

需要处理两种情况：

• 虚拟货币订单： payment_currency 为哨兵值 VC，而非法定货币的 ISO 4217 代码。
• 历史订单 在该字段存在之前创建的订单，其 payment_currency 为 null。通常应将该字段视为可选——它是向后兼容的新增字段，可能为 null 或缺失。

OrderContext Schema

键名	类型	描述
id	string	阿哈利姆生成的唯一订单标识符。
receipt_number	string	在玩家的收据中显示的收据号码。
amount	number	订单金额使用 currency, ，以 最小货币单位.
amount_before_discount	number	折扣前订单金额（以当地货币表示），在 最小货币单位.
currency	string	结账时向用户显示的订单货币（ISO 4217）。
payment_amount	number|null	最终收取的金额，货币单位为 payment_currency, 含税，以主要货币单位表示。
payment_currency	string|null	支付服务商收取的最终金额的货币（ISO 4217）。可能与以下不同： currency.
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	购买商品或礼包时在结账阶段兑换的优惠券（代码）列表。优惠券可提供折扣或奖励。请参阅下文的 Coupon Schema。
created_at	number	以 Unix 时间戳表示的订单创建日期。
paid_at	number|null	以 Unix 时间戳表示的订单支付日期。
creator	Creator|null	与该订单关联的创作者信息。
metadata	object|null	自定义的键值对数据对象，用于存储与订单相关的额外信息。
rewards	OrderRewards|null	与该订单关联的奖励，例如在所购商品之外额外发放的虚拟货币。

费用数据 Schema

键名	类型	描述
payment_system_fee_usd	number|null	支付处理费用（美分）。
aghanim_fee_usd	number|null	阿哈利姆服务费（美分）。
taxes_usd	number|null	税费（美分）。
tax_country	string|null	用于确定该订单适用税率的两字母国家代码（ISO 3166-1 alpha-2）。
tax_percent	number|null	应用于该订单的税率，以百分比表示（例如，20.5 表示 20.5%）。

OrderRewards Schema

键名	类型	描述
available	VirtualCurrencyReward[]	该订单可用的虚拟货币奖励列表。

VirtualCurrencyReward Schema

键名	类型	描述
type	string	奖励的类型。始终为 virtual_currency.
name	string|null	虚拟货币的名称。
virtual_currency_id	string	阿哈利姆生成的虚拟货币唯一 ID。
amount	number	将发放给玩家的虚拟货币数量。
sku	string	虚拟货币的 SKU，必须确保在游戏系统和阿哈利姆上保持一致。

Coupon Schema

键名	类型	描述
id	string	阿哈利姆生成的优惠券唯一 ID。
code	string	玩家在结账时兑换的优惠券代码（例如 WHATSAPP20, SNAG15）。此值用于归因分析和数据统计。
name	string	优惠券的内部名称。
type	string	优惠券的类型，可选值包括： bonus, discount, free_item, vc, non_benefit, discount_fixed, discount_reward_point.
discount_percent	integer|null	折扣百分比，适用于 discount 优惠券。
bonus_percent	integer|null	奖励百分比，适用于 bonus 优惠券。
bonus_fixed	integer|null	固定奖励数量，适用于 bonus 优惠券。

创作者 Schema

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

PlayerContext Schema

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

重新发送事件

如果投递尝试失败，item.add Webhook 会按照重试计划重新发送，适用于购买以及领取每日奖励、进度计划和滚动优惠奖励，以及激活免费商品优惠券。 如果玩家尝试领取商店免费商品或忠诚计划奖励但投递失败，该事件将不会重新发送。 玩家可以稍后再试。 当商品由 LiveOps 操作发放时，不会重新发送。

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

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

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

{
  "status": "error",
  "code": "declined",
  "message": "Purchase rejected: promotion has expired"
}

信息

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

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

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