订单创建 Webhook

Aghanim's 订单创建 webhook 通知您的游戏一个新的订单已创建。当玩家点击购买按钮并打开结帐页时触发。

该 Webhook 通过订单创建事件激活，可在 游戏 → Webhooks 中选择。

要求

要使用 Aghanim 的订单创建 Webhook，您需要按如下方式配置 Webhook 服务器：

HTTPS 端点，接受 POST Webhook 请求。
监听由 Aghanim 生成并签名的事件。
处理 Webhook 负载中包含的idempotency_key以防止重复处理 Webhook。
如果已成功将购买的商品添加到帐户，则响应 2xx 状态码；如有拒绝或错误，则用 4xx 或 5xx 状态码。

配置步骤

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

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

请求架构

下面是一个 order.created 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": "order.created",
  "event_data": {
    "amount": 9499,
    "company_id": "com_exTAxmkZQCO",
    "country": "US",
    "created_at": 1725547595,
    "currency": "USD",
    "game_id": "gm_exTAyxPsVwh",
    "id": "ord_eCacpFwavzi",
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "Crystals",
        "description": "统治你的对手，以这些巨大的晶体宝藏为荣。",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null
      }
    ],
    "modified_at": 1725547657,
    "player_id": "2D2R-OP3C",
    "receipt_number": "2409051289614565",
    "status": "created",
    "user_id": "usr_eymySUreClx",
    "metadata": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "checkout.purchase",
  "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": "order.created",
      "event_data": {
        "amount": 9499,
        "company_id": "com_exTAxmkZQCO",
        "country": "US",
        "created_at": 1725547595,
        "currency": "USD",
        "game_id": "gm_exTAyxPsVwh",
        "id": "ord_eCacpFwavzi",
        "items": [
          {
            "id": "itm_exTBZQmIlDz",
            "name": "Crystals",
            "description": "统治你的对手，以这些巨大的晶体宝藏为荣。",
            "sku": "crystals",
            "quantity": 480000,
            "price": 9499,
            "price_decimal": 94.99,
            "currency": "USD",
            "type": "item",
            "nested_items": null
          }
        ],
        "modified_at": 1725547657,
        "player_id": "2D2R-OP3C",
        "receipt_number": "2409051289614565",
        "status": "created",
        "user_id": "usr_eymySUreClx",
        "metadata": null
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "checkout.purchase",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

事件 Schema

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

键名	类型	描述
`id`	`string`	阿哈利姆生成的订单唯一标识符。
`company_id`	`string`	您的企业在阿哈利姆中的唯一标识符。
`game_id`	`string`	您的游戏在阿哈利姆中的唯一标识符。
`user_id`	`string`	用户在阿哈利姆游戏枢纽中的唯一标识符。
`player_id`	`string`	唯一的用于玩家身份验证的玩家标识符.
`status`	`string`	订单状态，可选值包括： `created`,`captured`,`paid`,`canceled`,`refunded`,`refund_requested`.
`amount`	`number`	订单金额使用最小货币单位.
`currency`	`string`	订单货币单位.
`country`	`string`	付款方式所关联的国家/地区。
`created_at`	`number`	以 Unix 时间戳表示的订单创建日期。
`modified_at`	`number`	以 Unix 时间戳表示的订单最后修改日期。
`items`	`Item[]`	包含已购买商品的详情。
`fees`	`Fees`	关于税费的信息。
`revenue_usd`	`number`	预期净收入会按预计汇率及支付手续费折算为美元美分。实际金额需与支付平台核账确认，一般于次月 10 日前完成结算。
`metadata`	`object\|null`	自定义的键值对数据对象，用于存储与订单相关的额外信息。
`creator`	`Creator\|null`	Information about creator associated with the order.

Item Schema

Key	Type	描述
`id`	`string`	阿哈利姆生成的商品唯一标识符。
`name`	`string`	商品名称。
`description`	`string\|null`	商品描述。
`sku`	`string`	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
`quantity`	`number`	商品数量。
`price`	`number`	商品价格使用最小货币单位.
`price_decimal`	`number`	商品价格以十进制单位表示。
`currency`	`string`	商品价格货币单位.
`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`	礼包内包含的所有单独商品组成的数组。

PlayerContext Schema

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

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