아이템 추가 웹훅

Aghanim은 Game Hub 내에서 플레이어의 활동에 따라 계정에 아이템을 할당하는 알림을 제공하는 중앙화된 웹훅을 제공합니다. 플레이어가 아이템을 부여받아야 하는 행동을 할 때마다 이 웹훅이 트리거됩니다. 이 가이드는 웹훅의 기능과 설정에 대한 자세한 인사이트를 제공합니다.

이 웹훅은 다음과 같은 경우에 실행됩니다:

플레이어가 게임 허브에서 구매를 진행할 때
플레이어가 게임 허브에서 무료 아이템 코드를 교환할 때
플레이어가 일일 보상 또는 충성도 프로그램 보상을 청구할 때

각 알림은 항목 적립을 위한 정당성이 포함된 reason 필드가 포함되어 있습니다.

요구 사항

Aghanim의 item.add 웹훅을 사용하려면 웹훅 서버를 다음과 같이 구성해야 합니다:

POST 웹후크 요청을 수락하는 HTTPS 엔드포인트.
Aghanim이 생성하고 서명한 이벤트를 수신합니다.
웹훅 페이로드에 포함된 idempotency_key를 처리하여 중복 웹훅 처리를 방지합니다.
플레이어의 계정에 지정된 아이템을 크레딧합니다.
성공적으로 처리된 경우에는 2xx 상태 코드로 응답하며, 거부 또는 오류의 경우에는 4xx 또는 5xx를 응답합니다.

구성

다음은 Aghanim 웹훅을 처리하고 게임에 크레딧하는 아이템을 알리는 엔드포인트에 대한 함수 템플릿입니다:

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>"  # 실제 웹훅 비밀 키로 교체하세요

    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>"  # 실제 웹훅 비밀 키로 교체하세요

  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>'; // 실제 웹훅 비밀 키로 교체하세요

  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>"  // 실제 웹훅 비밀 키로 교체하세요

  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)
  }
}

함수가 준비되면:

엔드포인트를 사용 가능하게 설정하세요.
Aghanim 계정에서 엔드포인트를 등록하세요 → 게임 → 웹훅 → 새 웹훅 해당 이벤트 유형을 선택하여.

대안으로, 웹후크 생성 API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

요청 스키마

아래는 예시입니다 item.add 웹훅 요청:

HTTP
cURL

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": "Crystals",
        "description": "Reign supreme over your rivals with this massive crystal treasure.",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null,
        "fallback_item": null
      }
    ],
    "reason": "Order paid 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 "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": "Crystals",
            "description": "Reign supreme over your rivals with this massive crystal treasure.",
            "sku": "crystals",
            "quantity": 480000,
            "price": 9499,
            "price_decimal": 94.99,
            "currency": "USD",
            "type": "item",
            "nested_items": null,
            "fallback_item": null
          }
        ],
        "reason": "Order paid 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"
    }'
            

이벤트 스키마

Key	유형	설명
`event_id`	`string`	Aghanim에 의해 생성된 고유 이벤트 ID.
`game_id`	`string`	Aghanim 시스템에서의 귀하의 게임 ID.
`event_type`	`string`	이벤트의 유형, `item.add` 이럴 경우.
`event_time`	`number`	유닉스 에포크 시간으로 된 이벤트 날짜.
`event_data`	`EventData`	이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
`idempotency_key`	`string`	웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다.
`request_id`	`string\|null`	이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
`sandbox`	`boolean`	이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
`trigger`	`string\|null`	The trigger that caused the event to be sent.
`transaction_id`	`string`	Aghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
`context`	`EventContext\|null`	이벤트에 대한 컨텍스트 정보.

EventContext 스키마

Key	유형	설명
`order`	`OrderContext\|null`	해당되는 경우 이벤트와 관련된 주문 정보입니다.
`player`	`PlayerContext\|null`	플레이어 정보를 추가하려면 웹훅 설정에서 "플레이어 컨텍스트 추가"를 활성화하세요.

EventData 스키마

Key	유형	설명
`player_id`	`string`	플레이어 인증을 위해 선택된 고유한 플레이어 ID.
`items`	`Item[]`	플레이어 계정에 크레딧될 아이템 배열입니다.
`reason`	`string`	웹훅을 트리거한 사람이 이해할 수 있는 형태의 설명입니다. 예: `주문 결제됨 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"를 사용할 때.

아이템 스키마

Key	Type	설명
`id`	`string`	Aghanim에 의해 생성된 아이템 ID.
`name`	`string`	아이템 이름.
`description`	`string\|null`	아이템 설명.
`sku`	`string`	게임과 Aghanim 측 모두에서 일치하는 아이템 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 스키마

Key	유형	설명
`id`	`string`	Aghanim에 의해 생성된 아이템 ID.
`name`	`string`	아이템 이름.
`description`	`string\|null`	아이템 설명.
`sku`	`string`	게임과 Aghanim 측 모두에서 일치하는 아이템 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 스키마

Key	유형	설명
`id`	`string`	Aghanim에 의해 생성된 고유 주문 ID.
`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`	예상 환율을 사용하여 USD로 변환된 결제 금액(예: $112.50는 112.50)입니다. 최종 값은 결제 제공자와 조정 후 다음 달 10일경에 확인됩니다.
`revenue_usd`	`number\|null`	예상 순수익은 예상 외환 환율 및 결제 수단 수수료를 사용하여 USD 센트로 변환됩니다. 최종 수치는 결제 제공업체와의 조정 후 다음 달 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`	유닉스 에포크 시간으로 된 주문 생성 날짜.
`paid_at`	`number\|null`	유닉스 에포크 시간으로 된 주문 결제 날짜.
`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.

Fees 스키마

Key	유형	설명
`payment_system_fee_usd`	`number\|null`	USD 센트 단위의 결제 처리 수수료.
`aghanim_fee_usd`	`number\|null`	USD 센트 단위의 Aghanim 플랫폼 수수료.
`taxes_usd`	`number\|null`	USD 센트 단위의 세금.
`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

Key	유형	설명
`available`	`VirtualCurrencyReward[]`	The list of virtual currency rewards available for the order.

The VirtualCurrencyReward schema

Key	유형	설명
`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

Key	유형	설명
`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.

크리에이터 스키마

Key	유형	설명
`name`	`string`	크리에이터 이름.
`payout_decimal_usd`	`number`	크리에이터 지불 금액 (USD) 주요 단위.

PlayerContext 스키마

Key	유형	설명
`player_id`	`string\|null`	고유한 플레이어 인증에 선택된 플레이어 ID.
`player`	`object\|null`	복합 인증 사용 시 플레이어 ID 구성 요소.
`attributes`	`Attributes`	Aghanim이 기대하는 기본 플레이어 속성.
`custom_attributes`	`CustomAttributes`	사용자 정의 플레이어 속성.

선택 사항: 자동 환불로 구매 거부

일부 경우에는, 게임 서버가 프로모션이 만료된 경우나 플레이어가 구매 조건을 충족하지 못하는 경우와 같은 상황에서 결제 완료 후 구매를 거부해야 할 수 있습니다. Aghanim은 이러한 시나리오의 자동 환불 처리를 지원합니다.

구매를 거부하려면 400 상태 코드로 응답합니다:

{
  "status": "error",
  "code": "declined",
  "message": "구매 거부: 프로모션이 만료되었습니다"
}

정보

자동 환불은 Aghanim 팀에 의해 설정되어야 합니다. code="declined"로 거부된 구매에 대한 자동 환불을 활성화하려면 통합팀에 연락하세요.

오류 코드를 포함한 자동 환불 구현에 대한 자세한 내용은 자동 결제 환불을 참조하세요.

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]