Webhook 概述

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

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

使用 AI 助手构建 Webhook 处理程序

阿哈利姆的 AI 编码工具 可以在您项目的技术栈中脚手架任何阿哈利姆 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_id	string	阿哈利姆生成的唯一事件标识符。
game_id	string	您的游戏在阿哈利姆中的唯一标识符。
event_type	string	事件的类型，可选值包括： player.verify, item.add, item.remove, order.paid, order.canceled, order.refunded, coupon.redeemed, ingame.push, ingame.popup.
event_time	number	以 Unix 时间戳表示的事件发生日期。
event_data	object	包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_key	string|null	即使出现重试情况，也能确保 Webhook 操作只执行一次。 可以是 null 具体取决于事件类型。
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	object|null	事件的相关上下文信息。

设置 Webhook 集成

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

要求

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

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

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

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

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

响应事件

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

• 2xx（成功）：此状态码表示事件已被 Webhook 函数按照其逻辑成功处理。
• 4xx（客户端错误）：行为取决于 webhook 类型：
  • 对于大多数 webhook，这些代码会触发重试序列。 若多次重试均告失败，阿哈利姆将终止后续尝试，相关事件数据将无法恢复。
  • 某些 webhook 会定义状态特定的行为而不是重试：HTTP 状态码决定阿哈利姆如何反应，而结构化的 JSON 错误主体则细化结果。 有关详细信息，请参阅每个 webhook 的文档（例如，Player Verify）。
  • 对于具有状态特定行为的 webhook，某些 4xx 状态是集成级别的信号，而非玩家级别的拒绝。 对于 Player Verify，400（validation_error，请求数据无效）和 401（invalid_signature，无法验证 Webhook 签名）会拒绝验证，但不会将玩家登出或显示面向玩家的消息——登录时玩家只是被拒绝进入，而在后台重新验证期间不采取任何操作。
• 5xx（服务器错误）：这些代码表示临时的服务器端故障（例如数据库不可用、内部异常）。 Aghanim 将根据重试计划自动重试这些请求——但 player.verify 除外，它是同步交付的，不会重试。

重试计划

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

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

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

player.verify 不会重试

重试计划仅适用于异步 Webhook——例如 item.add、item.remove、order.*、coupon.redeemed、subscription.* 和 fraud.reported。 player.verify Webhook 作为单次尝试同步交付，不会重试；5xx 响应会拒绝该次验证而不重试。 请参阅 Player Verify。

幂等性

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

• 商品添加 (item.add)
• 商品移除 (item.remove)
• 订单支付 (order.paid)
• 订单支付 (order.created)
• 订单退款 (order.refunded)
• 订单取消 (order.canceled)
• 优惠券已兑换 (coupon.redeemed)
• 订阅 (subscription.*)
• 已报告欺诈 (fraud.reported)

在处理这些 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. 使用点号 (.) 连接时间戳和原始负载形成签名数据。 确保使用 HTTPS 请求负载的原始字节，且不进行任何反序列化（转换为字符串或 JSON 解析）。 伪代码示例：

   signature_data = timestamp + '.' + raw_payload

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

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

   computed_signature = hmac_sha256(secret_key, signature_data)

   信息

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

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

   signature_data = timestamp + '.' + raw_payload
   computed_signature = hmac_sha256(secret_key, signature_data)
   
   # Compare the computed_signature and received_signature
   if computed_signature == received_signature:
     # Signature is valid
     process_webhook_event(raw_payload)
   else:
     # Signature is invalid
     ignore_webhook_event()

使用防火墙

使用数字签名可确保请求的安全性。 但是，如果您的安全策略需要使用防火墙来保护端点，也可以进行配置。 用于发送 webhook 请求的 IP 地址列表可根据请求提供。 请联系团队以获取该列表。

批处理模式

对于高吞吐量的事件类型（例如 analytics），你可以在 webhook 上启用 批处理模式。 事件不会以单个 HTTP 请求的形式接收，而是在一个时间窗口内收集，并以可下载的 JSONL 文件形式交付。 请参阅 Webhook 批量导出 了解设置和详细信息。

事件和触发器参考

阿哈利姆 Webhook 承载两个相关但不同的概念。 event_type 字段标识发送的内容——它对应于下面的文档页面，并决定负载的形状。 trigger 字段标识导致 Webhook 的原因——即导致阿哈利姆发出事件的具体操作（玩家活动、API 调用、LiveOps 操作或测试）。 单个触发器可以发出多种事件类型，单一事件类型也可以由多个触发器发出。

下面的参考列出了每种事件类型可能由哪些触发器引起。 条件行为用脚注编号标记，并在条件行为说明中解释。

向前兼容性

受支持的触发器集可能随时增长——随着新的平台功能上线，阿哈利姆可以在不事先通知的情况下引入新的 trigger 值。 请构建您的 Webhook 处理程序以容忍未知触发器：将您的核心逻辑基于（稳定的）event_type 进行分支，并且切勿因不在此参考中的 trigger 值而拒绝或崩溃。 请将下面的列表视为一个快照，而非封闭的枚举。

玩家事件

Event type	Emitted by
player.verify	hub.login, hub.interact¹, hub.purchase⁴, hub.store.open³, order.captured⁴, s2s.user.authorize⁵, s2s.player.issue_loyalty_points⁵, liveops.execute_action, test
player.lookup	hub.login, test
player.is_idle	hub.login, liveops.execute_action, test
player.marketing_consent.updated	hub.purchase, s2s.player.marketing_consent.grant, s2s.player.marketing_consent.revoke, dashboard.player.marketing_consent.revoke, checkout_profile.player.marketing_consent.revoke, test

商品和商店事件

Event type	Emitted by
item.add	coupon.redeemed, order.paid, hub.purchase, 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, checkout.purchase, liveops.execute_action, test
item.remove	order.canceled, order.refunded, checkout.cancel, checkout.refund, liveops.execute_action, test
store.get	hub.login², hub.store.open, hub.purchase, order.captured, test

订单事件

Event type	Emitted by
order.created	hub.purchase, test
order.paid	checkout.purchase, test
order.canceled	checkout.cancel, test
order.refunded	checkout.refund, test

其他核心事件

Event type	Emitted by
coupon.redeemed	hub.redeem, test
ingame.push	liveops.execute_action, test
ingame.popup	liveops.execute_action, test
campaign.custom	liveops.execute_action, test

分析事件

analytics.hub.* 和 analytics.checkout.* 聚合涵盖以下各个事件类型：

• analytics.hub.* — analytics.hub.sign_up, analytics.hub.login, analytics.hub.buy_click, analytics.hub.free_item_claimed
• analytics.checkout.* — analytics.checkout.submit_payment_form, analytics.checkout.back_store, analytics.checkout.back_game, analytics.checkout.pageview, analytics.checkout.pageshow, analytics.checkout.pagehide, analytics.checkout.pageexit

Event type	Emitted by
analytics.hub.*	hub.interact, test
analytics.checkout.*	checkout.interact, test

条件行为说明

¹ hub.interact 在玩家上次访问枢纽后每 6 小时触发一次，作为后台重新验证，并受冷却时间限制。 ² hub.login 在登录时预取商店。 ³ hub.store.open 仅在 Store Rules 包含 verify_player 操作时才发出 player.verify。 ⁴ hub.purchase 和 order.captured 仅在 Store 商品具有细分规则时才发出 player.verify。 ⁵ s2s.user.authorize 和 s2s.player.issue_loyalty_points 仅在用户为新创建时才发出 player.verify。 对同一用户的后续调用不会发出 Webhook。 ⁶ test 会为每种事件类型触发，并且仅可通过仪表板中的 Send test event 使用。

信息

某些事件类型在发出时不带 trigger 字段（例如 payment.*、subscription.*、fraud.reported 和批量交付事件）。 这些未包含在上面的参考中。

事件类型和函数行为

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

• 玩家验证
• 商品添加
• 商品移除
• 订单支付事件
• 订单创建事件
• 订单取消
• 退款
• 优惠券已兑换
• 移动推送
• 游戏内弹窗
• 订阅
• 已报告欺诈

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