V Cloud

Topics and Subscription Quick Guide

Description: This page explains how to create topics for monitoring blockchain events and configure webhook callback addresses for these topics. A topic consists of a "transaction type" and a set of parameter filter conditions (such as recipients, smart contract parameters, etc.).

1. Concepts

  • Topic: Event type that can filter by defining specific values for certain parameters or use wildcard matching by leaving them unset
  • Callback Address (Endpoint): The address of your personal service that receives webhook notifications when subscribed events occur. If your service is inaccessible three consecutive times, it will be charged once
  • When an event is matched, the platform sends an HTTP POST (JSON) notification to this address.

2. Creating Topics

  1. VSYS chain network: Currently supports testnet and mainnet
  2. Event type (event_type): BlockAppendEvent: New block events. StatusUpdateEvent: Events involving transactions that cause state changes in accounts or contracts
  3. Supported transaction types: Currently supports PaymentTransaction and TokenExecutionTransaction
  4. Callback address (webhook_url): Complete URL for receiving POST requests

Topic Name Structure

Smart contract execution event topic:

/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/ExecuteContract/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA/contract_type/TokenContract/function_index/3/function/send/contract_sender/*/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv

This topic defines an event for: subscribing to StatusUpdated events on VSYS mainnet for ExecuteContract type transactions, targeting contract CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA (TokenContract) function_index 3 (send function), with recipient AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv and unlimited sender.

More Details:

  • /chain/vsysIndicates the blockchain type is VSYS. Other blockchain types may be supported in the future

  • /network/mainnet: Indicates the network is mainnet (not testnet).

  • /event_type/StatusUpdated: Event type is StatusUpdated, typically indicating transaction/event status changes (such as from pending to confirmed, failed, etc.).

  • /transaction_type/ExecuteContract: Transaction type is contract execution (ExecuteContract), indicating transactions generated by contract calls.

  • /contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA: Contract ID (contract address), only matches events from this contract.

  • /contract_type/TokenContract: Contract category is TokenContract (token contract).

  • /function_index/3: Contract function index is 3 (contracts may number functions by index), equivalent to the following /function/send.

  • /function/send: Explicit function name is send (Token sending). Elements after this represent filter parameters during smart contract execution

  • /contract_sender/*: Sender uses wildcard *, indicating matching any contract caller (replace * with specific address to limit to certain sender).

  • /contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv: Specifies contract token recipient address, only matches events related to this recipient.

Regular payment events:

/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/Payment/sender/*/recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv

The corresponding transaction_type is Payment, payer and payee parameters correspond to sender and recipient, which can be exact values or wildcards, but at least one must have an exact value

New block events:

/chain/vsys/network/mainnet/event_type/BlockAppended

3. Filter Field Recommendations

  • Standard transaction fields: sender, recipient
  • Contract calls: contractID (contract ID), function (method name), contract_sender (contract transfer sender), contract_recipient (contract transfer recipient), caller (wallet address or contract ID calling this contract)
  • Support for nested and array indexing: Use dots and brackets for access

4. Callback (Webhook) Format Example

POST body (application/json):

{
	"timestamp": 1234567890,
	"count": 1,
	"events": [
		{
			"type": 3,
			"uuid": "testing-uuid-totaly-notfake",
			"payload": {
				"constract": false,
				"address": "really-real-address",
				"balanceDiff": 30,
				"newBalance": 40,
				"sourceTxs": [
					{
						"type": 2,
						"id": "36Yr41ZgZixZoJLWczHiHBNsFFZdkvSgMpRBmTUdUZPc",
						"recipient": "ATrBCSLCVZn3wev8Hx7iybANHrmBdCn8uQ7",
						"proofs": [{
								"proofType": "Curve25519",
								"publicKey": "RKzKv6ZFyudJ3nBPguhervM7kDri5KpjHzR9DNupJ9U",
								"address": "ATrBCSLCVZn3wev8Hx7iybANHrmBdCn8uQ7",
								"signature": "4gUZVwX5KAbPxamskyccPnZEX9swYC9Xo2SmfTGhaNMXek9w2J4FNwHigctaZiM9P1RwSwcm6faB6yYbkR9B7Pyi"
						}],
						"timestamp": 1551842469000234562,
						"amount": 1000,
						"height": 2075349,
						"status": "Success",
						"feeCharged": 0,
						"attachment": "62fb634f8c149c5bcab5587c;CnDYHs3vqBXyXFp3dDUvz9iiTgWEqioamoptTEgt7QR8"
					}
				],
				"sourceBlocks": {
					"version": 9,
					"timestamp": 0,
					"reference": "fake-reference",
					"SPOSConsensus": {
						"mintTime": 0,
						"mintBalance": 20
					},
					"resourcePricingData": {
						"computation": 300,
						"storage": 4096,
						"memory": 512,
						"randomIO": 300,
						"sequentialIO": 3000
					},
					"TransactionMerkleRoot": "IDKWhatTheHellIsThis",
					"transactions": [
						{
							"type": 2,
							"id": "36Yr41ZgZixZoJLWczHiHBNsFFZdkvSgMpRBmTUdUZPc",
							"recipient": "AU7nJLcT1mThXGTT1KDkoAtfPzc82Sgay1V",
							"proofs": [{
								"proofType": "Curve25519",
								"publicKey": "RKzKv6ZFyudJ3nBPguhervM7kDri5KpjHzR9DNupJ9U",
								"address": "ATrBCSLCVZn3wev8Hx7iybANHrmBdCn8uQ7",
								"signature": "4gUZVwX5KAbPxamskyccPnZEX9swYC9Xo2SmfTGhaNMXek9w2J4FNwHigctaZiM9P1RwSwcm6faB6yYbkR9B7Pyi"
							}],
							"timestamp": 1551842469000234562,
							"amount": 100,
							"height": 2075349,
							"status": "Success",
							"feeCharged": 0
						}
					],
					"generator": "testgen",
					"signature": "testsig",
					"fee": 30,
					"blocksize": 256,
					"height": 666,
					"transaction count": 1
				}
			},
			"referenceRules": {
				"abc": 123
			}
		}
	]
}

Server-side verification recommendations:

  • Check HTTP status code (platform typically requires 200 OK)
  • Verify callback signature: generate the signature from the CanonicalRequest (including the x-sdk-time and User-Agent headers) and validate it using the public-key.
  • Avoid processing duplicate notifications (use tx_hash for deduplication)

5. Common Scenario Examples

  • Only monitor large transfers to a specific address:
/transaction_type/Payment/sender/*/recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
  • Monitor specific smart contract methods (like send) with contract_recipient parameter as certain user(such as AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv):
/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/ExecuteContract/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA/contract_type/TokenContract/function_index/3/function/send/contract_sender/*/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
  • Multiple condition:
/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/ExecuteContract/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA/contract_type/TokenContract/function_index/3/function/send/contract_sender/ARD6RdjBMjJRfQcdTaxc7hSesFcRnWGGQLB/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv

6. Operation Process Summary

  1. Create topic in console or via API (specify tx_type, filters, webhook_url)
  2. Verify webhook receiving capability (return 200, support HTTPS)
  3. Monitor notification logs after going live and adjust filters as needed

For sample API call formats or more field descriptions, please specify your platform API (REST/Web UI) preference.

Usage Process

Activate Service Account

Before using node watcher, you need to activate your account (account based on wallet address), newly activated account. Click the register button to activate the service and start using it. If the account is already activated, the page will display the account's resource usage information for this service.

activate account

Subscribe to New Block Events

Simply select the corresponding network and set the endpoint address for receiving webhooks. Description information is optional and used for marking and describing usage information. Currently supports VSYS testnet and mainnet networks. sub block append

Subscribe to Payment Events

This event is for VSYS COIN payment events. You need to select PaymentTransaction from the Transaction Type list. Sender and Recipient serve as filter conditions for coin payment events, and at least one of these two parameters must have a valid value. sub payment

Subscribe to Smart Contract Execution Events

Currently supported smart contract types are: AtomicSwapContract, TokenContract, and SplitTokenContract. First, you need to input a Contract ID that exists on the selected network. If it's a valid Contract, the supported Functions will be displayed in the Functions select dropdown.

sub contract: Input ID

Function is a required field. After selection, the component below will display the filter parameter types supported by the Function. At least one option must be valid. sub contract: Set filter for function

Subscription Management

After creating subscriptions, users can manage their created subscription topics through the buttons in the Actions column on the right side of the subscription list. manage sub Currently supported management operations:

  • Enable and disable subscriptions: Users can turn subscriptions on or off. When disabled, webhook sending will stop, and the topic subscription will not be charged during the disabled period. After enabling the subscription, the system starts sending webhook events corresponding to the subscription topic that occur after enabling. Events that occurred during the disabled period will not be sent.
  • Delete subscription: Remove the subscription from the system, webhooks will no longer be sent.
  • Update subscription information: Subscription updates can only modify webhook receiving address information and subscription description information update sub
Last Updated: 10/16/2025, 6:08:28 AM

←