Webhook

A developer guide to webhook payloads, business and billing enums, event protocol migration, response requirements, retries, and configuration.

The current event protocol version is 20260930, provided in the X-EVENT-VERSION header. This upgrade renames some values of data.business_type in delegation events and data.billing_item_type in balance events. Update enum parsing and event routing using the migration tables below. data.delegation_type remains deprecated; new integrations should use business_type.

When signing is enabled, follow Webhook Signing and Verification to verify the raw request body before parsing the event. The guide covers User Center settings, three language examples, and a fixed test vector.

Overview

When an event occurs on the platform, CatFee will send an HTTP POST request to your configured callback address (callbackUrl). You need to:

1. Receive the raw request body. If signing is enabled, verify the signature before parsing JSON.

2. Identify the event type via the X-EVENT-TYPE header.

3. Return HTTP 200 after successful processing.

4. Otherwise, the platform will retry according to its retry policy.

---

Configure the Callback URL

• Location: Go to User Center → API Settings.

• Configuration: Fill in callbackUrl and check the event types you want to subscribe to.

• Protocol: Both HTTP and HTTPS are supported.

• Identification: The event type is indicated by the request header X-EVENT-TYPE.

• Note: Dynamic subscription via API is not supported.

---

Request Headers

Each webhook request includes the following HTTP headers:

Header Name	Description
X-EVENT-ID	Unique event ID (idempotency key)
X-EVENT-TYPE	Event type (enum EventType)
X-EVENT-VERSION	Event protocol version, currently 20260930
X-EVENT-TIMESTAMP	Included when signing is enabled; Unix timestamp in seconds for this send
X-EVENT-SIGNATURE	Included when signing is enabled; HMAC-SHA256 v1 signature; verification guide

---

Event Structure (JSON)

The request body of a webhook is JSON, using snake_case for top-level fields:

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

data contains the event-specific payload. See the examples and event data definitions below for its fields.

Event Types (EventType)

Currently supported types: EVENT_BALANCE, EVENT_TRON_MATE_SUBSCRIPTION, EVENT_DELEGATION, EVENT_ADDRESS_MONITOR (If you receive an unknown type, record and ignore it.)

When migrating from earlier versions, note that balance_type and billing_type were replaced by action_type and billing_item_type. This event protocol upgrade keeps these field names and changes some enum values. Update your JSON deserialization models, field validation, and message templates accordingly.

Example: Balance Change (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"
  }
}

Example: TRON Mate Subscription (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..."
  }
}

Example: Delegation Confirmation (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
  }
}

The address and transaction hash in this example are placeholders. In delegation events, payment_timestamp and delegation_timestamp are Unix timestamps in milliseconds, and duration is in minutes. Use the top-level event_id to identify the event; there is no separate order_id field inside data.

Delegation Business Types and Compatibility

Field	Purpose	Integration guidance
resource_type	The delivered resource: ENERGY or BANDWIDTH	Use it to distinguish Energy from Bandwidth
business_type	The service associated with the delegation	Use this string enum to route events by service in new integrations
delegation_type	The legacy delegation classification	Deprecated; retained for compatibility with existing receivers

Common resource-related business types are listed below. The full enum is available in the DelegationEventData definition. This is a shared business classification; not every business type necessarily produces delegation events.

business_type	Service
BUSINESS_TIME_BASED_RENTAL	Hourly Energy
BUSINESS_TRON_MATE	TRON Mate
BUSINESS_SEAMLESS_SERVICE	Seamless Energy
BUSINESS_ENERGY_RESELLING	Energy Subleasing
BUSINESS_FLASH_REFILL	Flash Refill
BUSINESS_SWEEP_ASSISTANT	Sweep Assist
BUSINESS_TRANSACTION_HANDOFF	Transaction Handoff
UNKNOWN_BUSINESS_TYPE	Unspecified or unknown business

For existing integrations:

1. Add business_type to your delegation event model. Allow it to be absent for compatibility with older notifications.

2. Gradually switch service routing to business_type. Combine it with resource_type when you also need to distinguish the delivered resource.

3. Keep parsing delegation_type until you have migrated your handling of older notifications. The fields represent different classifications and should not be treated as a one-to-one replacement.

4. Handle missing values, UNKNOWN_BUSINESS_TYPE, UNRECOGNIZED, and future enum values through a fallback path, and record the original payload. Do not assume an unknown business is Hourly Energy or reject an entire callback merely because it contains a new field.

The current definitions retain both business_type and the deprecated delegation_type, but historical notifications may not have a specific business classification.

Event Protocol 20260930 Enum Migration

The OpenAPI changes are limited to the enum names below and the example value for business_type; event structures and field types are unchanged. Enums are sent as strings in JSON, so strict enum validation, event routing conditions, and conditional logic in templates must be updated.

Delegation events: data.business_type

Previous value	Value in protocol 20260930	Service
BUSINESS_HOUR_ENERGY	BUSINESS_TIME_BASED_RENTAL	Hourly Energy (time-based rental)
BUSINESS_ENERGY_SUBLET	BUSINESS_ENERGY_RESELLING	Energy Subleasing
BUSINESS_FLASH_SERVICE	BUSINESS_FLASH_REFILL	Flash Refill
BUSINESS_REALTIME_COLLECTION	BUSINESS_SWEEP_ASSISTANT	Sweep Assist
BUSINESS_ONE_ORDER_ONE_PAYMENT	BUSINESS_TRANSACTION_HANDOFF	Transaction Handoff
BUSINESS_ADDRESS_CHECK	BUSINESS_ADDRESS_SCREENING	Address Screening

Balance events: data.billing_item_type

Previous value	Value in protocol 20260930	Billing item
BILLING_ITEM_HOUR_ENERGY	BILLING_ITEM_TIME_BASED_RENTAL	Hourly Energy (time-based rental)
BILLING_ITEM_ENERGY_SUBLET	BILLING_ITEM_ENERGY_RESELLING	Energy Subleasing
BILLING_ITEM_FLASH_ENERGY	BILLING_ITEM_FLASH_REFILL_ENERGY	Flash Refill Energy
BILLING_ITEM_FLASH_BANDWIDTH	BILLING_ITEM_FLASH_REFILL_BANDWIDTH	Flash Refill Bandwidth
BILLING_ITEM_REALTIME_COLLECTION_ENERGY	BILLING_ITEM_SWEEP_ASSISTANT_ENERGY	Sweep Assist Energy
BILLING_ITEM_REALTIME_COLLECTION_BANDWIDTH	BILLING_ITEM_SWEEP_ASSISTANT_BANDWIDTH	Sweep Assist Bandwidth
BILLING_ITEM_ONE_ORDER_ONE_PAYMENT_ENERGY	BILLING_ITEM_TRANSACTION_HANDOFF_ENERGY	Transaction Handoff Energy
BILLING_ITEM_ONE_ORDER_ONE_PAYMENT_BANDWIDTH	BILLING_ITEM_TRANSACTION_HANDOFF_BANDWIDTH	Transaction Handoff Bandwidth
BILLING_ITEM_ADDRESS_CHECK_SUBSCRIPTION	BILLING_ITEM_ADDRESS_SCREENING_SUBSCRIPTION	Address Screening Subscription

Enum values not listed here are unchanged. See the event data definitions below for the complete enums. The old names in these tables are no longer part of the new enum lists. During migration, receivers should accept the old names and normalize them to the new names when processing historical records or older notifications. This compatibility logic belongs in the receiver; it does not mean the new version sends both names.

For UNKNOWN_BUSINESS_TYPE, UNKNOWN_BILLING_ITEM_TYPE, UNRECOGNIZED, or future values, retain the original payload and use a fallback path so an enum change does not prevent the entire callback from being parsed. Use X-EVENT-VERSION to identify the event protocol version. Continue to accept the old enum names in the tables above when processing older notifications and historical records.

Business Types in Message Templates

Delegation notification templates can use {{business_type}} directly, without a data. prefix. For example, a Telegram message template can contain:

{
  "chat_id": "YOUR_CHAT_ID",
  "text": "Business: {{business_type}}; Resource: {{resource_type}}; Receiver: {{receiver}}"
}

{{business_type}} renders the enum name, such as BUSINESS_TIME_BASED_RENTAL. The existing {{delegation_type}} variable remains available, but new templates should use the business type. In the Webhook JSON payload, the corresponding path is data.business_type.

The new OpenAPI definition uses BUSINESS_TIME_BASED_RENTAL as the example value for business_type. Use the delegation event example above to check payload parsing and template rendering.

Event Data Definitions

---

Request Format

• Method: POST

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

• Headers: Must include X-EVENT-ID, X-EVENT-TYPE, X-EVENT-VERSION

Example Request

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"
  }
}

---

Event Data Definitions

The DelegationEvent object

Describes Energy or Bandwidth delegation details, including resource_type, business_type, the deprecated delegation_type, receiver, payment, duration, quantity, staked TRX, and delegation transaction details. See the OpenAPI schema above for the complete field definitions.

The BalanceEvent object

Describes account balance changes, including recharge, transfer, dApp consumption, API billing, refund, and others.

The TronMateSubscriptionEvent object

Describes subscription information for TRON Mate, including payment amount, payment time, subscription type (BASIC or PRO), and address.

The AddressMonitorEvent object

Describes a monitored-address transfer, including the transaction and block identifiers, monitored address, sender and recipient, amount, currency, chain, and payment time.

---

Response Requirements

⚠️ NOTICE: Please return success to inform the notification server that you have successfully received and handled the event. Once the notification server receives a success response, it stops retrying.

• After successful handling, you must return:

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

success

• The platform treats HTTP 200 as success; otherwise, it will retry.

---

Retry Mechanism

If your endpoint does not return status 200, the system retries the notification.

Retry Schedule

Up to 10 attempts, with the following intervals:

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

After 10 consecutive failures, the system stops retrying and logs the failure.

---

Idempotency Recommendation

• Use X-EVENT-ID as the idempotency key.

• If the event has already been processed, immediately return 200.

---

Example Code

The following basic receiver examples assume signing is disabled. When signing is enabled, use the signed receiver examples and verify the signature before parsing JSON. Production receivers also need persistent idempotency.

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: handle event

  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: handle event logic

    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: handle event

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

---

FAQ

Q1: Can I return JSON? Yes. As long as the HTTP status is 200, the response format does not matter.

Q2: Does HTTP work? Yes, both HTTP and HTTPS are supported.

Q3: Can I subscribe dynamically? No. Subscriptions can only be configured in the User Center.

Q4: How to handle different event types? Use the X-EVENT-TYPE header to branch logic.

Q5: Are events ordered? The system tries to preserve order for the same event type, but it’s not guaranteed.

Q6: How should I handle event versioning? The current protocol version is 20260930. Use the X-EVENT-VERSION header to select your parsing logic and ignore unknown fields. Allow business_type to be absent when handling older delegation notifications.

Q7: Has delegation_type been removed? No. It is deprecated but is still included for compatibility with existing receivers. Use business_type for new integrations and templates.

Q8: Why does enum parsing fail after upgrading to event protocol 20260930? Some business_type and billing_item_type strings have been renamed. Use the migration tables to update receiver models, event routing, and template conditions. Handle old names in historical notifications and future unknown values; strict validation that only accepts the old enum list will reject the new values.

Q9: How can I distinguish TRON Mate Basic and Pro subscription-opening (Open) orders from refill orders?

For an EVENT_DELEGATION notification, first check that data.business_type is BUSINESS_TRON_MATE and data.resource_type is ENERGY. Then use data.duration to identify the order:

Plan	Order type	data.duration
Basic	Delegation order created when opening a subscription (Open)	-4
Pro	Delegation order created when opening a subscription (Open)	-3
Basic	Energy refill order	-2
Pro	Energy refill order	0

In webhook payloads, duration is an integer in minutes. The negative values and 0 above are special business markers, not actual rental periods. Basic and Pro Open orders have different values and should be classified separately.

When applying these rules:

• Do not identify a Pro refill order from duration = 0 alone. Other instant refill services also use this value, so always check business_type as well.

• Basic Bandwidth protection orders also use duration = -2, but their resource_type is BANDWIDTH. Handle these separately from Energy refill orders.

• If an older notification lacks business_type, or you receive a combination not listed above, log it and apply your compatibility handling. Do not default to classifying it as a Basic or Pro refill order.

EVENT_TRON_MATE_SUBSCRIPTION is a separate subscription billing notification, distinct from the Open delegation notification described above. For that event, use data.subscribe_type to identify the plan: SUBSCRIBE_BASIC for Basic and SUBSCRIBE_PRO for Pro. Do not use this event to identify refill orders.

---

Version: v1.4.2 (2026-10-03); event protocol version: 20260930