跳至主要内容

Webhook 批量导出

Aghanim 不会通过 webhook 请求直接传递事件，而是在一段时间窗口内收集事件，将其存储为 JSONL 文件，并发送一个包含预签名 URL（用于下载批次）的 batch.ready webhook 通知。

工作原理

  1. 你创建一个 webhook，并在其上启用批处理模式。
  2. Aghanim 会在一个时间窗口内收集与你的 webhook 订阅匹配的事件。
  3. 批次就绪后，Aghanim 会向你的端点发送一条 batch.ready 通知，其中包含用于下载批处理文件的预签名 URL。
  4. 你需要在 URL 过期（24 小时）之前下载并处理 JSONL 文件。

启用批处理模式

通过控制台

  1. 在 Aghanim 控制台中前往 游戏 → Webhooks → 新建 Webhook。
  2. 输入你的端点 URL 并配置 webhook secret。
  3. 选择你希望以批处理方式接收的事件类型（例如 order.created、order.paid）。
  4. 打开批处理模式选项。
  5. 保存该 webhook。

通过 API

使用 Create Webhook API 方法，并将 batch_mode 参数设置为 true。

信息

以下事件不支持批处理模式：

  • player.verify、player.lookup、store.get — 这些事件需要你的服务器提供同步响应，这与批量传递不兼容。
  • item.add、item.remove — 为避免物品传递延迟，不应对这些事件进行批处理。

处理批处理通知

当批次就绪时，Aghanim 会向你的端点发送一条 batch.ready 通知。 你的端点必须：

  • 接受 HTTPS POST 请求。
  • 验证请求的签名。
  • 在过期（24 小时）之前，使用提供的已签名 URL 下载批处理文件。
  • 处理 JSONL 文件——每一行都是一个单独的 JSON 事件对象。
  • 使用 2xx 状态码表示成功处理，并使用 4xx 或 5xx 表示错误。

通知 Schema

下面是一个 batch.ready Webhook 请求示例：

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": "batch.ready",
  "event_data": {
    "signed_url": "https://s2s-api.aghanim.com/v1/batch_export/download?token=eyJhb...NiIs",
    "format": "jsonl",
    "expires_at": 1710786400
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

事件 Schema

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

EventContext Schema

键名类型描述
orderOrderContext|null与事件相关的订单信息（如果适用）。
playerPlayerContext|null（可选）玩家信息。如需启用，请在webhook设置中选择“添加玩家上下文”。

EventData Schema

键名Type描述
signed_urlstring用于下载 JSONL 文件的预签名 URL。 24 小时后过期。
formatstring文件格式。 始终为 jsonl。
expires_atinteger已签名 URL 过期时的 Unix 时间戳。

批处理文件格式

每个批处理文件都是一个 JSONL 文件——每行一个 JSON 事件。 每一行都包含一个完整的 webhook 事件对象，并与您订阅的事件类型相匹配。

示例文件内容:

{"event_type":"order.created","event_data":{"id":"ord_eCacpFwavzi","amount":9499,"company_id":"com_exTAxmkZQCO","country":"US","created_at":1725547595,"currency":"USD","game_id":"gm_exTAyxPsVwh","items":[{"id":"itm_exTBZQmIlDz","name":"Crystals","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,"creator":null},"event_time":1725547595,"event_id":"whevt_eCacFaIUauSnNfykXTfNChtsjDE","idempotency_key":"idmpt_aXRlb...JkX2VFS","request_id":"c0482e8b-b180-3003-7735-5568b2e4710a","sandbox":false,"trigger":"checkout.purchase","transaction_id":"whtx_eCacFaIUauS","context":null,"game_id":"gm_exTAyxPsVwh"}
{"event_type":"order.paid","event_data":{"id":"ord_eCacpFwavzi","amount":9499,"company_id":"com_exTAxmkZQCO","country":"US","created_at":1725547595,"currency":"USD","game_id":"gm_exTAyxPsVwh","revenue_usd":9099.123,"fees":{"aghanim_fee_usd":10.11,"payment_system_fee_usd":15.123,"taxes_usd":481.198933},"items":[{"id":"itm_exTBZQmIlDz","name":"Crystals","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":"paid","user_id":"usr_eymySUreClx","metadata":null,"creator":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"}

需要技术支持？
联系我们的集成技术团队： [email protected]

On this page