Webhook 概览

Aghanim 利用 webhooks 来提醒您的游戏关于 Aghanim 生成的游戏中心中玩家触发的事件，从而促进 Aghanim 与您的游戏之间的基本通信。本指南概述了 Aghanim webhooks 的工作原理和结构。

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

结构

Aghanim 服务将 HTTP POST 请求发送到您的 webhook 服务器，携带的 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"
}

设置 webhook 集成

要管理 Aghanim 的事件，您需要开发一个或多个函数。这个选择取决于您是希望通过单个端点处理所有事件，还是使用多个端点，每个端点专注于特定事件或不同逻辑。

要求

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

HTTPS 端点，接受 POST webhook 请求。
监听由 Aghanim 生成并签名的事件。
处理 webhook 负载中包含的 idempotency_key，以防止处理重复的 webhooks。
适当处理传入的请求，例如根据玩家 ID 验证玩家对游戏中心的访问权限，或将购买的物品记入玩家账户。
对访问批准或物品记入响应 2xx 状态代码，而对拒绝或错误响应 4xx 或 5xx。

在 Aghanim 中注册您的端点

使您的端点（s）可用。
在 Aghanim 帐户中注册您的端点 → 游戏 → Webhooks → 新建 Webhook 并选择您希望由此端点处理的事件。
复制生成的秘密密钥，并在您的 webhook 功能中指定它以进行请求签名验证。

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

响应事件

响应 webhooks 时，Aghanim 期望：

2xx（成功）：此代码表示事件已成功根据逻辑被 webhook 功能处理。
4xx 或 5xx (错误)：这些代码触发重试序列，根据重试计划。如果重试失败，Aghanim 会停止尝试，并且事件会丢失。

重试计划

Aghanim 通过使用指数退避的已定义重试策略确保 webhook 消息的交付。如果初始交付尝试失败，每个后续尝试都会按照以下顺序进行：

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

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

幂等性

Aghanim 在以下webhooks中包含一个 idempotency_key，以便进行安全重试时，不会在游戏方触发相同操作两次：

在处理这些 webhooks 时，依靠 idempotency_key 的唯一性，以确保动作仅执行一次：

只有在首次收到带有唯一 idempotency_key 的 webhook 时执行预期动作（例如授予物品）。
如果再次收到带有相同 idempotency_key 的 webhook，请忽略它并响应状态代码 200。

例如，若发生连接错误并且 Aghanim 重试发送 webhook，idempotency_key 将保持不变。这确保了游戏方面的动作仅执行一次，从而可以安全地重复请求而不会产生意外影响。

安全 Webhook

Aghanim 的每个请求都带有一个独特的、基于秘密密钥的签名，您可以通过它来验证请求的真实性。 Webhook 事件包括特为安全检查设计的特定标头：

X-Aghanim-Signature：事件负载的 HMAC-SHA256 签名。
X-Aghanim-Signature-Timestamp：事件在 Unix 时间纪元中触发的确切时间。

验证请求完整性：

从收到的事件中提取原始负载和 X-Aghanim-Signature-Timestamp 标头。
用点（.）连接时间戳和原始负载来形成签名数据。 Python 示例：

signature_data = timestamp + '.' + raw_payload

从您的 Aghanim 帐户中检索特定于您的 webhook 的秘密密钥 → 游戏 → Webhooks → 您的 webhook。
使用秘密密钥生成一个 HMAC-SHA256 哈希。 Python 示例：

computed_signature = hmac_sha256(secret_key, signature_data)

信息

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

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

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()

事件类型和函数行为

Aghanim 提供以下类型的事件。了解您的函数响应这些事件的预期行为以及这些事件的含义：

需要帮助吗？
联系我们的集成团队 integration@aghanim.com

结构​

设置 webhook 集成​

要求​

在 Aghanim 中注册您的端点​

响应事件​

重试计划​

幂等性​

安全 Webhook​

事件类型和函数行为​

结构