兑换码 Webhook

Aghanim 提供一个兑换码 Webhook，当玩家使用免费商品的兑换码时通知您的游戏，并提供该事件的详情。

该 Webhook 通过兑换码已兑换事件激活，可在 游戏 → Webhook 中选择。

警告

要向玩家账户添加游戏内商品，请使用 item.add Webhook。当 item.add 提供的信息不足时，兑换码 Webhook 旨在提供更详细的数据。

要求

要使用来自 Aghanim 的兑换码已兑换 Webhook，请按如下方式配置您的 Webhook 服务器：

HTTPS 端点，可接收 POST Webhook 请求。
监听由 Aghanim 生成并签名的事件。
使用 2xx 状态码表示成功处理，使用 4xx 或 5xx 状态码表示拒绝或错误。

配置步骤

为 coupon.redeemed Webhook 处理开发一个函数。
部署您的端点使其可访问。
在 Aghanim 账户中注册您的端点 → 游戏 → Webhook → 新建 Webhook，选择对应的事件类型。

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

Request schema

下面是一个 coupon.redeemed Webhook 请求示例：

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": "coupon.redeemed",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "coupon": {
      "code": "WELCOME",
      "sku": "crystals",
      "redeemed_at": 1725548450
    },
    "item": {
      "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
    }
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.redeem",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": 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": "coupon.redeemed",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "coupon": {
          "code": "WELCOME",
          "sku": "crystals",
          "redeemed_at": 1725548450
        },
        "item": {
          "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
        }
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "hub.redeem",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

事件 Schema

键名	类型	描述
`event_id`	`string`	阿哈利姆生成的唯一事件标识符。
`game_id`	`string`	您的游戏在阿哈利姆中的唯一标识符。
`event_type`	`string`	事件的类型， `coupon.redeemed` 在此情境下。
`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

键名	Type	描述
`player_id`	`string`	用于玩家身份验证的唯一玩家 ID。
`coupon`	`Coupon`	包含兑换码数据的优惠券对象。
`items`	`Items`	商品对象，包含兑换码使用时提供的免费商品详情。

优惠券对象

键名	Type	描述
`货币代码`	`string`	兑换码。
`sku`	`string`	使用兑换码时提供的免费商品 SKU。
`redeemed_at`	`数字`	兑换码使用时间的 Unix 时间戳。

触发器值

Value	描述
`hub.redeem`	当兑换免费商品的优惠券时。
`test`	在 Dashboard 中使用 "Send test event" 时。

Item Schema

Key	Type	描述
`id`	`string`	阿哈利姆生成的商品唯一标识符。
`name`	`string`	商品名称。
`description`	`string\|null`	商品描述。
`sku`	`string`	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
`quantity`	`number`	商品数量。
`type`	`string`	商品类型，可选值包括： `item`, `bundle`.
`nested_items`	`NestedItem[]\|null`	礼包内包含的所有单独商品组成的数组。
`fallback_item`	`Item\|null`	如果无法向玩家发放主要商品，系统将提供的备选商品。
`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.

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