跳至主要内容

Webhook 概述

阿哈利姆使用 Webhook 通知您的游戏关于玩家在阿哈利姆生成的游戏枢纽中触发的事件。 这些 Webhook 促进了阿哈利姆与您游戏之间的关键通信。 本指南概述了阿哈利姆 Webhook 的工作原理和结构。

Webhook 是 Aghanim 发送到您在 Aghanim 账户中指定的 URL 下的 游戏 → Webhooks → 新建 Webhook 的 HTTP 回调。 这些请求由特定事件触发，并携带包含相关事件数据的 JSON 负载。

Webhook 通用流程图
Webhook 通用流程图

Schema

阿哈利姆服务向您的 Webhook 服务器发送 HTTP POST 请求，请求中包含采用以下结构的 JSON 格式事件数据：

{
  "event_type": "player.verify",
  "event_data": {"player_id": "2D2R-OP3C"},
  "event_time": 1725534306,
  "event_id": "whevt_eBZXsUEITGeDcILaZFUvPthxkr",
  "idempotency_key": null,
  "sandbox": false,
  "trigger": "hub.login",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "transaction_id": "whtx_eBZXsUEITGeDcILaZFUvPthxkr",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

事件 Schema

键名类型描述
event_idstring阿哈利姆生成的唯一事件标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
event_typestring事件的类型，可选值包括： player.verify, item.add, item.remove, order.paid, order.canceled, order.refunded, coupon.redeemed, ingame.push, ingame.popup.
event_timenumber以 Unix 时间戳表示的事件发生日期。
event_dataobject包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_keystring|null即使出现重试情况，也能确保 Webhook 操作只执行一次。 可以是 null 具体取决于事件类型。
request_idstring|null如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
sandboxboolean标识事件是否来自沙盒测试环境的指示器。
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstring阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
contextobject|null事件的相关上下文信息。

设置 Webhook 集成

要管理来自阿哈利姆的事件，您需要开发一个或多个函数。 您可以通过单个端点处理所有事件，或使用多个端点，每个专注于特定事件或不同逻辑。

要求

您的函数应符合以下要求和逻辑：

  • HTTPS 端点，可接收 POST Webhook 请求。
  • 监听由阿哈利姆生成并签名的事件。
  • 处理 Webhook 负载中包含的 idempotency_key，以防止重复处理 Webhook。
  • 妥善处理传入请求，如根据玩家 ID 验证玩家访问游戏枢纽的权限，或向玩家账户添加已购商品。
  • 对访问批准或商品添加成功返回 2xx 状态码，对拒绝或错误返回 4xx 或 5xx 状态码。

在阿哈利姆中注册您的端点

  1. 使您的端点可访问。
  2. 在 Aghanim 账户中选择要通过此端点处理的事件，注册您的端点(s) → 游戏 → Webhooks → 新建 Webhook。
  3. 复制生成的 Secret Key，并在您的 Webhook 函数中指定它用于请求签名验证。

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

响应事件

阿哈利姆应收到的 Webhook 响应示例：

  • 2xx（成功）：此状态码表示事件已被 Webhook 函数按照其逻辑成功处理。
  • 4xx 或 5xx（错误）：这些状态码会根据 重试计划 触发重试序列。 若多次重试均告失败，阿哈利姆将终止后续尝试，相关事件数据将无法恢复。

重试计划

阿哈利姆使用指数退避重试策略来确保 Webhook 消息的传递。 如果初始传递尝试失败，阿哈利姆将按照以下顺序重试：

  • 失败后立即重试
  • 5 秒后重试
  • 5 分钟后重试
  • 30 分钟后重试
  • 2 小时后重试
  • 5 小时后重试
  • 10 小时后重试
  • 再过 10 小时后重试
  • 如果所有重试都失败，消息传递将被放弃

例如，如果 Webhook 消息连续三次传递失败，成功传递将在初次尝试后约 35 分钟 5 秒发生。

幂等性

阿哈利姆在以下 Webhook 中设置了 idempotency_key，通过该机制可安全进行请求重试，确保不会在游戏端重复执行同一操作：

在处理这些 Webhook 时，系统将基于 idempotency_key 的唯一性特征，确保相关操作仅被执行一次：

  • 仅在首次收到具有唯一 idempotency_key 的 Webhook 时执行预期操作（如发放商品）。
  • 如果再次收到带有相同 idempotency_key 的 Webhook，忽略它并返回 200 状态码。

例如，如果发生连接错误且阿哈利姆 重试 发送 Webhook，idempotency_key 将保持不变。 这确保了游戏端的操作只执行一次，允许安全地重复请求而不会产生意外副作用。

安全 Webhooks

阿哈利姆的每个请求都携带一个基于 secret key 的唯一签名，可以让您验证请求的真实性。 Webhook 事件包含专为安全检查设计的特定标头：

  • X-Aghanim-Signature：事件负载的 HMAC-SHA256 签名。
  • X-Aghanim-Signature-Timestamp：事件被触发的确切时间（Unix 时间戳）。

验证请求完整性：

  1. 从收到的事件中提取原始负载和 X-Aghanim-Signature-Timestamp 标头。

  2. 使用点号 (.) 连接时间戳和原始负载形成签名数据。 Python 示例：

    signature_data = timestamp + '.' + raw_payload

  3. 从您在 Aghanim 账户的 游戏 → Webhooks → 特定 Webhook 中检索秘密密钥。

  4. 使用 Secret Key 生成 HMAC-SHA256 哈希。 Python 示例：

    computed_signature = hmac_sha256(secret_key, signature_data)
信息

使用十六进制表示法表示计算得到的签名。

  1. 将 computed_signature 与接收到的事件中的 X-Aghanim-Signature 标头进行比较。 如果匹配，表示该事件来自受信任的来源。 Python 示例：

    signature_data = timestamp + '.' + raw_payload
    computed_signature = hmac_sha256(secret_key, signature_data)

    # 比较 computed_signature 和 received_signature
    if computed_signature == received_signature:
      # 签名有效 
      process_webhook_event(raw_payload)
    else:
      # 签名无效
      ignore_webhook_event()

事件类型和函数行为

阿哈利姆提供以下类型的事件。 了解您的函数应如何响应这些事件，以及这些事件的含义：

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

On this page