Coupon Redeemed Webhook

Aghanim offers a coupon redeemed webhook to notify your game when a redeem code for a free item has been used by a player, providing detailed information about the event.

This webhook is activated through the Coupon redeemed event, selectable in Game → Webhooks.

警告

To credit in-game items to player accounts, use the item.add webhook. The coupon redeemed webhook is designed to provide detailed data when item.add is insufficient.

Requirements

To use the redeemed coupon webhook from Aghanim, you should have the webhook server configured as follows:

HTTPS endpoint, accepting POST webhook requests.
Listen for events, generated and signed by Aghanim.
Respond with 2xx status codes to signal successful processing, and 4xx or 5xx for denial or errors.

Configuration

Develop a function for the coupon.redeemed webhook processing.
Make your endpoint available.
Register your endpoint within Aghanim account → Game → Webhooks → New Webhook by choosing the corresponding event type.

Alternatively, you can register your endpoint within Aghanim using the Create Webhook API method.

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设置中选择“添加玩家上下文”。

The EventData schema

Key	Type	Description
`player_id`	`string`	The unique Player ID chosen for player authentication.
`coupon`	`Coupon`	The coupon object containing the redeem code data.
`item`	`Item`	The item object containing details about the free item provided upon redeeming the code.

The Coupon object

Key	Type	Description
`code`	`string`	Redeem code.
`sku`	`string`	Free item SKU provided upon the redeem code usage.
`redeemed_at`	`number`	Code usage date in Unix epoch time.

The Trigger values

Value	Description
`hub.redeem`	When a coupon for a free item is redeemed.
`test`	When using the "Send test event" in the Dashboard.

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`	如果无法向玩家发放主要商品，系统将提供的备选商品。

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

NestedItem Schema

键名	类型	描述
`id`	`string`	阿哈利姆生成的商品唯一标识符。
`name`	`string`	商品名称。
`description`	`string\|null`	商品描述。
`sku`	`string`	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
`quantity`	`number`	商品数量。
`type`	`string`	商品类型，可选值包括： `item`, `bundle`.
`nested_items`	`NestedItem[]\|null`	礼包内包含的所有单独商品组成的数组。

需要技术支持？
联系我们的集成技术团队： integration@aghanim.com