回调（Webhook）

面向集成平台事件推送的开发者，说明回调结构、业务与计费枚举、事件协议升级迁移、返回要求、重试策略与接入配置。

当前事件协议版本为 20260930，通过请求头 X-EVENT-VERSION 标识。本次升级调整了代理事件 data.business_type 和余额事件 data.billing_item_type 的部分枚举名称，接收方需更新枚举解析与业务分支，具体见下方迁移对照表。data.delegation_type 仍为已废弃字段，新接入请使用 business_type。

开启签名后，请先按回调签名与验签校验原始请求体，再解析事件。新子页面包含签名开关、密钥获取、三种语言接入示例和固定测试向量。

概览

当平台发生事件时，会通过 HTTP POST 调用你配置的回调地址（callbackUrl）。你需要：

1. 接收原始请求体；已开启签名时先验签，再解析 JSON 数据；

2. 根据 X-EVENT-TYPE 识别事件类型；

3. 成功处理后 返回 HTTP 200 ；

4. 否则平台将按重试策略重新通知。

---

配置回调地址

• 入口位置：进入 用户中心 → API 设置 页面。

• 配置项：填写 callbackUrl 并勾选要订阅的事件类型。

• 协议：支持 HTTP 或 HTTPS。

• 路径：平台通过请求头 X-EVENT-TYPE 标识事件类型。

• 不可通过 API 动态订阅。

---

请求头说明

平台每次回调都会附带以下 HTTP 头：

Header 名称	描述
X-EVENT-ID	事件唯一 ID（幂等键）
X-EVENT-TYPE	事件类型（枚举 EventType）
X-EVENT-VERSION	事件版本号，当前为 20260930
X-EVENT-TIMESTAMP	开启签名时附带，本次发送的 Unix 秒级时间戳
X-EVENT-SIGNATURE	开启签名时附带，HMAC-SHA256 v1 签名；验签说明

---

事件结构（JSON）

平台推送的回调请求体为 JSON，顶层字段采用 snake_case：

{
  "event_type": "EVENT_BALANCE",
  "event_id": "aabbccdd-1122-3344-5566-77889900",
  "data": {}
}

data 为对应事件的数据体，具体字段见下方示例和事件数据定义。

事件类型（EventType）

当前有效事件类型：EVENT_BALANCE、EVENT_TRON_MATE_SUBSCRIPTION、EVENT_DELEGATION、EVENT_ADDRESS_MONITOR（如收到未知类型，请记录并忽略）。

事件类型	事件名称	触发场景	回调数据结构	说明与处理
EVENT_BALANCE	余额变动事件（Balance Changed）	当用户账户余额发生变化（充值、提现、质押收益、消费、能量支出等）	BalanceEventData 包含字段：action_type、billing_item_type、coin_type、amount_sun、balance、balance_usdt、timestamp、remark	用于通知账户余额的实时变化；可据此更新资金记录或展示统计。
EVENT_TRON_MATE_SUBSCRIPTION	波场伴侣订阅事件（TRON Mate Subscription）	订阅 CatFee 波场伴侣（BASIC / PRO 等）成功时触发	TronMateSubscriptionEventData 包含字段：payment_amount_sun、payment_timestamp、subscribe_type、address	通知有新订阅发生；每个地址每24小时触发一次。
EVENT_DELEGATION	代理确认事件（Delegation Confirmed）	用户能量(或带宽)代理确认上链后触发	DelegationEventData 包含字段：resource_type、business_type、delegation_type（已废弃）、receiver、payment_amount_sun、payment_timestamp、duration、quantity、staked_sun、delegation_hash、delegation_timestamp	通知能量(或带宽)代理确认成功，可用于账单记录同步。

从更早版本迁移时，注意余额事件字段已由 balance_type、billing_type 改为 action_type、billing_item_type。本次事件协议升级保留这些字段名，调整的是部分枚举值；请同步更新 JSON 反序列化模型、字段校验及消息模板。

示例：余额变动（EVENT_BALANCE）

{
  "event_type": "EVENT_BALANCE",
  "event_id": "aabbccdd-1122-3344-5566-77889900",
  "data": {
    "action_type": "BALANCE_ACTION_RECHARGE",
    "billing_item_type": "UNKNOWN_BILLING_ITEM_TYPE",
    "coin_type": "USDT",
    "amount_sun": 1000000,
    "balance": 500000000,
    "balance_usdt": 2000000,
    "timestamp": 1760505600,
    "remark": "transfer in"
  }
}

示例：订阅（EVENT_TRON_MATE_SUBSCRIPTION）

{
  "event_type": "EVENT_TRON_MATE_SUBSCRIPTION",
  "event_id": "22334455-6677-8899-aabb-ccddeeff",
  "data": {
    "payment_amount_sun": 5000000,
    "payment_timestamp": 1760505600,
    "subscribe_type": "SUBSCRIBE_PRO",
    "address": "TGxxx..."
  }
}

---

示例：代理确认（EVENT_DELEGATION）

{
  "event_type": "EVENT_DELEGATION",
  "event_id": "delegation-event-id",
  "data": {
    "resource_type": "ENERGY",
    "business_type": "BUSINESS_TIME_BASED_RENTAL",
    "delegation_type": "DELEGATION_NORMAL",
    "receiver": "TReceiver",
    "payment_amount_sun": 2000000,
    "payment_timestamp": 1761021630421,
    "duration": 60,
    "quantity": 65000,
    "staked_sun": 100000000,
    "delegation_hash": "delegation-hash",
    "delegation_timestamp": 1761021630421
  }
}

示例中的地址和交易 Hash 为占位值。代理事件中的 payment_timestamp 和 delegation_timestamp 使用 Unix 毫秒时间戳，duration 的单位为分钟。事件标识使用顶层 event_id，data 中没有单独的 order_id 字段。

代理业务类型与兼容处理

字段	用途	接入建议
resource_type	本次交付的资源：ENERGY 或 BANDWIDTH	判断交付的是能量还是带宽
business_type	本次代理所属的业务	新接入用此字段区分业务，取值为枚举字符串
delegation_type	旧版代理分类	已废弃，仅为兼容旧接收方保留

常见的资源业务取值如下；完整枚举见下方 DelegationEventData 定义。枚举属于通用业务分类，不代表每种业务都会产生代理事件。

business_type	业务
BUSINESS_TIME_BASED_RENTAL	小时能量
BUSINESS_TRON_MATE	波场伴侣
BUSINESS_SEAMLESS_SERVICE	无感能量
BUSINESS_ENERGY_RESELLING	能量转租
BUSINESS_FLASH_REFILL	速充服务
BUSINESS_SWEEP_ASSISTANT	归集助手
BUSINESS_TRANSACTION_HANDOFF	能量直达（Transaction Handoff）
UNKNOWN_BUSINESS_TYPE	未指定或未知业务

已有接入建议按以下步骤迁移：

1. 在代理事件的数据模型中增加 business_type，允许该字段缺失，以兼容旧版通知。

2. 将业务分发逻辑逐步切换为读取 business_type；需要区分资源时，再结合 resource_type 判断。

3. 保留对 delegation_type 的解析，直到旧版通知处理逻辑完成迁移。两个字段是不同的分类，不应做简单的一一替换。

4. 遇到字段缺失、UNKNOWN_BUSINESS_TYPE、UNRECOGNIZED 或未来新增枚举时，进入兼容分支并记录原始数据。不要把未知业务默认当作小时能量，也不要仅因新增字段而拒绝整条回调。

当前定义仍保留 business_type 和已废弃的 delegation_type，但历史通知不保证都有明确的业务分类。

事件协议 20260930 枚举迁移对照

本次 OpenAPI 定义的变化集中在以下枚举名称，以及 business_type 的示例值；事件结构和字段类型未变。JSON 中的枚举以字符串传递，因此接收方的严格枚举校验、业务分发条件和模板中的条件判断都需要同步更新。

代理事件：data.business_type

升级前	协议 20260930 取值	业务
BUSINESS_HOUR_ENERGY	BUSINESS_TIME_BASED_RENTAL	小时能量（按时租赁）
BUSINESS_ENERGY_SUBLET	BUSINESS_ENERGY_RESELLING	能量转租
BUSINESS_FLASH_SERVICE	BUSINESS_FLASH_REFILL	速充服务
BUSINESS_REALTIME_COLLECTION	BUSINESS_SWEEP_ASSISTANT	归集助手
BUSINESS_ONE_ORDER_ONE_PAYMENT	BUSINESS_TRANSACTION_HANDOFF	能量直达
BUSINESS_ADDRESS_CHECK	BUSINESS_ADDRESS_SCREENING	地址筛查

余额事件：data.billing_item_type

升级前	协议 20260930 取值	计费项目
BILLING_ITEM_HOUR_ENERGY	BILLING_ITEM_TIME_BASED_RENTAL	小时能量（按时租赁）
BILLING_ITEM_ENERGY_SUBLET	BILLING_ITEM_ENERGY_RESELLING	能量转租
BILLING_ITEM_FLASH_ENERGY	BILLING_ITEM_FLASH_REFILL_ENERGY	速充能量
BILLING_ITEM_FLASH_BANDWIDTH	BILLING_ITEM_FLASH_REFILL_BANDWIDTH	速充带宽
BILLING_ITEM_REALTIME_COLLECTION_ENERGY	BILLING_ITEM_SWEEP_ASSISTANT_ENERGY	归集助手能量
BILLING_ITEM_REALTIME_COLLECTION_BANDWIDTH	BILLING_ITEM_SWEEP_ASSISTANT_BANDWIDTH	归集助手带宽
BILLING_ITEM_ONE_ORDER_ONE_PAYMENT_ENERGY	BILLING_ITEM_TRANSACTION_HANDOFF_ENERGY	能量直达能量
BILLING_ITEM_ONE_ORDER_ONE_PAYMENT_BANDWIDTH	BILLING_ITEM_TRANSACTION_HANDOFF_BANDWIDTH	能量直达带宽
BILLING_ITEM_ADDRESS_CHECK_SUBSCRIPTION	BILLING_ITEM_ADDRESS_SCREENING_SUBSCRIPTION	地址筛查订阅

未列出的枚举值保持不变，完整取值见下方事件数据定义。上表的旧名称已不在新版枚举列表中；迁移期间，建议接收方按表兼容旧名称并归一化为新名称，以便处理历史记录或旧版通知。此兼容逻辑由接收方实现，不表示新版会同时发送新旧枚举名称。

对于 UNKNOWN_BUSINESS_TYPE、UNKNOWN_BILLING_ITEM_TYPE、UNRECOGNIZED 或未来新增值，请保留原始数据并进入兼容分支，避免枚举更名导致整条回调解析失败。根据 X-EVENT-VERSION 识别事件协议版本；处理旧版通知和历史记录时，仍需兼容上表中的旧枚举名称。

消息模板中的业务类型

代理通知模板可直接使用 {{business_type}}，无需添加 data. 前缀。例如 Telegram 消息模板：

{
  "chat_id": "YOUR_CHAT_ID",
  "text": "业务：{{business_type}}；资源：{{resource_type}}；接收地址：{{receiver}}"
}

{{business_type}} 渲染为枚举名称，例如 BUSINESS_TIME_BASED_RENTAL；原有的 {{delegation_type}} 仍可使用，建议新模板改用业务类型。Webhook JSON 中对应的读取路径为 data.business_type。

新版 OpenAPI 中 business_type 的示例值为 BUSINESS_TIME_BASED_RENTAL，可用上方代理事件示例检查回调解析和模板渲染。

---

回调请求格式

• 方法：POST

• Content-Type：application/json; charset=utf-8

• 请求头：包含 X-EVENT-ID、X-EVENT-TYPE、X-EVENT-VERSION

示例请求

POST /callback HTTP/1.1
Host: example.com
Content-Type: application/json
X-EVENT-ID: aabbccdd-1122-3344-5566-77889900
X-EVENT-TYPE: EVENT_BALANCE
X-EVENT-VERSION: 20260930

{
  "event_type": "EVENT_BALANCE",
  "event_id": "aabbccdd-1122-3344-5566-77889900",
  "data": {
    "action_type": "BALANCE_ACTION_RECHARGE",
    "billing_item_type": "UNKNOWN_BILLING_ITEM_TYPE",
    "coin_type": "USDT",
    "amount_sun": 1000000,
    "balance": 500000000,
    "balance_usdt": 2000000,
    "timestamp": 1760505600,
    "remark": "transfer in"
  }
}

事件数据定义

---

返回要求

⚠️ NOTICE: Please return success to notify the notification server after successfully receiving the callback request. After the notification server receives success, the notification stops.

• 成功接收后，必须返回：

  HTTP/1.1 200 OK
  Content-Type: text/plain; charset=utf-8
  

• 平台以返回 200 为成功，否则将重试。

---

重试机制

若响应非 200 ，系统会进行重试。

重试次数与间隔

共 10 次通知，间隔如下：

0s / 15s / 30s / 3m / 10m / 20m / 30m / 60m / 3h / 6h

若连续 10 次均失败，则系统放弃并记录。

---

幂等处理建议

• 请使用 X-EVENT-ID 作为幂等键。

• 对于已处理事件，应直接返回 200 。

---

示例代码

以下为未启用签名时的基本接收示例。开启签名后，请使用签名接收端示例，在解析 JSON 前完成验签。生产环境还需实现持久化幂等。

Node.js (Express)

import express from 'express';
const app = express();
app.use(express.json());
const processed = new Set();

app.post('/callback', (req, res) => {
  const eventId = req.header('X-EVENT-ID');
  if (processed.has(eventId)) return res.status(200).type('text/plain').send('success');
  processed.add(eventId);

  const evt = req.body; // { event_type, data }
  // TODO: 处理事件

  res.status(200).type('text/plain').send('success');
});

app.listen(8080);

Java (Spring Boot)

@RestController
public class WebhookController {
  private final Set<String> processed = Collections.synchronizedSet(new HashSet<>());

  @PostMapping(value = "/callback", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.TEXT_PLAIN_VALUE)
  public ResponseEntity<String> handle(@RequestHeader("X-EVENT-ID") String id,
                                       @RequestBody Map<String, Object> evt) {
    synchronized (processed) {
      if (processed.contains(id)) return ResponseEntity.ok("success");
      processed.add(id);
    }

    // TODO: 事件处理逻辑

    return ResponseEntity.ok("success");
  }
}

Python (FastAPI)

from fastapi import FastAPI, Request, Header, Response
app = FastAPI()
processed = set()

@app.post("/callback")
async def webhook(req: Request, x_event_id: str = Header(None)):
    if x_event_id in processed:
        return Response(content="success", media_type="text/plain")
    processed.add(x_event_id)

    evt = await req.json()
    # TODO: 事件处理

    return Response(content="success", media_type="text/plain")

---

FAQ

Q1：返回 JSON 可以吗？ 可以。只要返回的HTTP状态为200即可。

Q2：HTTP 支持吗？ 支持 HTTP 与 HTTPS。

Q3：可否动态订阅？ 不支持，仅能在用户中心配置。

Q4：如何分发不同事件？ 根据请求头 X-EVENT-TYPE 实现逻辑分支。

Q5：事件会乱序吗？ 系统尽量保证同类事件顺序，但不作绝对保证。

Q6：事件版本如何处理？ 当前协议版本为 20260930。根据 X-EVENT-VERSION 选择解析方式，未知字段请忽略；处理旧版代理通知时，允许 business_type 缺失。

Q7：delegation_type 是否已删除？ 没有。该字段已标记废弃，但仍输出以兼容旧接收方。新接入及新模板请使用 business_type。

Q8：升级到事件协议 20260930 后为什么枚举解析失败？ 部分 business_type 和 billing_item_type 字符串已更名。请按迁移对照表更新接收模型、业务分支和模板条件，并兼容历史通知中的旧名称与未来未知值；仅保留旧枚举列表的严格校验会拒绝新版取值。

Q9：如何区分波场伴侣基础版、专业版的订阅订单（Open）和补能订单？

对于 EVENT_DELEGATION 代理通知，先确认 data.business_type 为 BUSINESS_TRON_MATE，且 data.resource_type 为 ENERGY，再根据 data.duration 区分：

版本	订单类型	data.duration
基础版（Basic）	开通订阅时的代理订单（Open）	-4
专业版（Pro）	开通订阅时的代理订单（Open）	-3
基础版（Basic）	补能订单	-2
专业版（Pro）	补能订单	0

duration 在回调中是以分钟为单位的整数；上表中的负数和 0 是特殊业务标记，不代表实际租赁时长。两种 Open 订单的值不同，不能合并判断为同一种版本。

判断时还需注意：

• 不能只凭 duration = 0 判断为专业版补能，其他速充业务也使用该值，必须同时检查 business_type。

• 基础版带宽保护订单也使用 duration = -2，但 resource_type 为 BANDWIDTH，应与能量补能订单分开处理。

• 旧版通知若缺少 business_type，或收到未列出的字段组合，请记录并按兼容逻辑处理，不要默认归为基础版或专业版补能。

EVENT_TRON_MATE_SUBSCRIPTION 是单独的订阅扣费通知，与上述 Open 代理订单通知不同。该事件通过 data.subscribe_type 区分版本：SUBSCRIBE_BASIC 为基础版，SUBSCRIBE_PRO 为专业版；不要用该事件判断补能订单。

---

版本：v1.4.2（2026-10-03）；事件协议版本：20260930