TransactionFormatVersion.v2 is Custody Infrastructure's new and improved standard for providing structured parsable webhook notifications to your listening machine.
Webhooks are a method of having the Custody Infrastructure backend notify a designated listening machine whenever a specific event occurs. These events can be any of four types and are further refined by including filters as you register the webhook.
Registering and unregistering (creating and deleting) webhooks can only be done from the MPC's command line and requires that you have API access configured for your user.
The webhook notification sent to the listener is both highly detailed and standardized. This article covers how to understand the information your listener is receiving.
Example .v2 output

Transaction Types
There are four types of transactions that you can configure your webhooks to fire for.
Input Transaction
An input transaction is any transaction where the monitored account receives assets. It filters transactions by:
CoinSymbol: What asset are you monitoring?
Machine: What machine is receiving the funds, Cold Vault or MPC?
AccountIds: You can monitor multiple accounts with a single webhook; which ones do you want alerts for?
MinAmount: Let's not bother with small change. How much does an account need to receive in a single transaction to be worth notifying you?
Confirmations: How locked into the blockchain must a transaction be before you're told about it? You can supply up to ten values here.
The above filters are mandatory for every input transaction webhook.
Output Transaction
An output transaction is any transaction where the monitored account attempts to send assets. It filters transactions by:
AlertEvent:This filter MAY optionally include CoinSymbol, Machine, and AccountIds as detailed in Input Transaction.
The filter REQUIRES that an AlertEvent be specified. This event can be any one of the following:
"No funds available"
"Created"
"Failed-Limits"
"Failed-Technical"
"Sent"
"Timeout occurred"
"Waiting to be processed"
"Canceled"
"Waiting for external co-signer"
"Failed-Policy"
Confirmations:This filter may optionally include CoinSymbol, Machine, AccountIds.
The filter requires that Confirmations be specifies, as detailed in Input Transaction.
Alert balance
The alert balance webhook only monitors the main wallet of each specified account. It lets you know whenever a balance crosses a selected threshold. You can optionally use the AlertEvent filter to specify whether you get notified only when the threshold is crossed in a specific direction. It takes the following filters:
CoinSymbol: What asset are you monitoring?
Threshold: When do you want to be notified?
The above filters are mandatory for every Alert Balance webhook. The webhook may be further refined with the addition of any of the following optional filters:
Machine: What machine is receiving the funds, Cold Vault or MPC?
AccountIds: You can monitor multiple accounts with a single webhook; which ones do you want alerts for?
AlertEvents: This can be either "Below" or "Above" and will cause the webhook to send an alert only when the threshold is crossed in the specified direction.
Approve Transaction
This event cannot be filtered. It will alert the listener whenever a transaction is approved.
Understanding the Webhook Output
Webhooks send notifications to your listener in the form of a JSON. Each alert consists of multiple properties and nested objects following standard schemas (outlined in the tabs below). In the case of multiple addresses being involved as sources or destination, relevant objects will be repeated more than once.
Not all properties are relevant to every cryptocurrency. This article outlines everything that MAY appear in a webhook v2 notification, but some items may return "null" or be omitted entirely in real-world scenarios.
Timestamp: string, "Time the transaction was sent to the network represented as milliseconds since epoch"
Symbol: string, "Currency symbol (e.g., BTC, ETH)"
Confirmations: string, "Number of confirmations for the transaction"
Type: integer, "Transaction type (either deposit(0) or withdrawal(1))"
Sources: array, items: "TransactionToPresentSource" (see tab 1 below)
Destinations: array, items: "TransactionToPresentDestination" (see tab 2 below)
Fees: "TransactionToPresentFees" (See tab 3 above)
DestinationMemo: string, nullable, "Memo for the destination, if available (relevant for XLM,XRP,CASPR,HBAR)"
TransactionId: string, nullable, "Transaction ID, if available"
BlockNumber: string, nullable, "Block number, if applicable"
Branch: string, nullable, "Relevant for Tezos, Near, Plokadot, Solana, Tron"
TransactionErrorInBlock: boolean, "Indicates if there was an error in the transaction"
RawTransaction: string, nullable, "Raw transaction data, if applicable"
SourceMemo: string, nullable, "Memo for the source, if available (relevant for XLM,XRP)"
Schema Interpretation
The returned webhook output contains information specific to the triggering event. This may include information as JSON objects that follow one or more of the schema illustrated below.
Schema
Tab
TransactionToPresentSource
1
TransactionToPresentDestination
2
TransactionToPresentFees
3
AdditionalDepositTransactionData
4
AdditionalWithdrawalTransactionData
5
TokenizationConfiguration
6
DataSigningInformation
7
TransactionToPresentContract
8
Scroll sideways or use the scroll bar to access all tabs.
1
2
3
4
5
6
7
8
1 - TransactionToPresentSource
Description
This schema describes the origin point of a transaction. The system gets the origin address from the transaction itself, then checks the address book to populate the additional information such as ContactName. If the information is not in the address book, then ContactName, WalletId, CustomerId, and WalletName will return "null"
Required:
Address
ContactName
WalletId
CustomerId
WalletName
Below is an example of the schema layout and the datatype of each property. The outputs for UTXO and EVM transactions contain slightly different information.
Address: Address that sent the transaction.
ContactName: Contact name associated with the source.
WalletId: Wallet ID associated with the source.
CustomerId: Customer ID associated with the source.
WalletName:Wallet name associated with the source.
TransactionId: Transaction ID (UTXO only).
Index: Index (UTXO only).
Amount: Amount in the asset's smallest units (UTXO only).
2 - TransactionToPresentDestination
Description
This schema describes the destination point of a transaction. The system gets the destination address from the transaction itself, then checks the address book to populate the additional information such as ContactName. If the information is not in the address book, then ContactName, WalletId, WalletName, CustomerId, AccountId, and Machine will return "null"
Required:
Address
Amount
WalletId
WalletName
CustomerId
AccountId
Machine
DepositAddressIndex
Below is an example of the schema layout and the datatype of each property. The output for Tezos (XTZ) includes additional information.
Address: Address that the transaction is sent to.
ContactName: Contact name associated with the destination.
Amount: Amount in the asset's smallest units (UTXO only).
WalletId: Wallet ID associated with the source.
WalletName:Wallet name associated with the source.
CustomerId: Customer ID associated with the source.
AccountId: rgerg
Machine: 0=cold, 1=mpc
DepositAddressIndex: owiemv
StorageToDestination: Tezos Only
OperationType: Tezos only
3 - TransactionToPresentFees
Description
This schema describes the fees paid for a transaction. The system gets the information from the transaction itself. Not all fields are relevant for every currency type. Keys irrelevant to the transaction will return "null" or will not appear at all.
Required:
MaxTotalFee
FeeActuallyPaid
Below is an example of the schema layout and the datatype of each property. Some keys are only relevant for specific currencies.
FeeActuallyPaid: Fee actually paid.
StorageLimit: Relevant for Tezos.
Tip: Relevant for Polkadot.
MaxGasPrice: Relevant for EVMs , ERC20 tokens, Tezos, Casper, Near, Starknet.
MaxTotalFee: Maximum total fee.
FeePerByte: Fee per byte, relevant only for BCH, ADA.
FeePerVByte: Fee per virtual byte , relevant only for BTC.
MaxPriorityFee: Relevant only for EVMs and ERC20 tokens with London fork.
GasPrice: Relevant for EVMs , ERC20 tokens, Tezos, Casper, Near, Starknet.
GasLimit: Relevant for EVMs , ERC20 tokens, Tezos, Cosmos, Near, Starknet.
GasUsed: Relevant for EVMs , ERC20 tokens, Tezos, Cosmos, Near, Starknet.
4 - AdditionalDepositTransactionData
Description
This schema describes additional information for a deposit transaction. The system gets the information from the transaction itself. Not all fields are relevant for every currency type. Keys irrelevant to the transaction will return "null" or not appear.
Required:
none
Below is an example of the schema layout and the datatype of each property. Some keys are only relevant for specific currencies.
TraceId: Relevant for EVMs, ERC20, Solana.
Initiator: Relevant for EVMs and ERC20 tokens.
InternalTransaction: Indicates if it is an internal transaction (smart contract), Relevant for EVMs and ERC20 tokens.
5 - AdditionalWithdrawalTransactionData
Description
This schema describes additional information for a withdrawal transaction. The system gets the information from the transaction itself. Not all fields are relevant for every currency type. Keys irrelevant to the transaction will return "null" or not appear.
TokenizationConfiguration may be included in this schema. For information about it, see tab 6.
Required:
DataSigningInformation:
Type
Payload
Signature
Staking:
Operation
Info
Below is an example of the schema layout and the datatype of each property. Some keys are only relevant for specific currencies.
The AdditionalWithdrawalTransactionData schema may include any of the following nested objects:
TokenizationConfiguration: Detailed in tab 6.
DataSigningInformation: Detailed in tab 7.
Staking: Click the Staking button below to view details.
Machine: Machine associated with the destination 0=Cold, 1=MPC.
TransactionDescription: Description of the transaction.
UserId: User ID associated with the transaction.
UserName: User name associated with the transaction.
AccountId: Account ID associated with the transaction.
StatusId: Status ID associated with the transaction. See Status Table, below.
AdditionalStatusInformation:
Additional status information.
InitiatingSystem: Initiating system associated with the transaction.
TokenizationConfiguration: Relevant only for EVMs. For details of this object's properties, see tab 6.
TransactionToken: Transaction token.
ApprovalRequestId: Approval request ID.
Expiration: Expiration time.
DataSigningInformation: Relevant for EVMs, Near and Stellar. See tab 7.
TokenReplacedByFee: Relevant for EVMs and ERC20 tokens.
ReplaceByFeeUserId: Relevant for EVMs and ERC20 tokens.
Staking: Relevant for Casper, Cardano, Tezos, Tron, Polkadot, Cosmos, Near, Solana.
ContractData: Relevant for EVMs , Hedera, Tezos. See tab 8.
Status Table:
Status ID
Name
Description
0
APPROVED
Created
1
FAILED_LIMITATIONS
The transaction amount or fees exceed the initiator's limits and cannot be completed.
2
FAILED_TECHNICAL
The transaction has failed due to technical issues.
3
SIGNED
The transaction is signed and ready to transmit to the blockchain.
4
SENT
The transaction has been transmitted to the blockchain.
5
FAILED_NO_FUNDS
The transaction cannot be completed due to a lack of funds in the originating wallet.
6
FAILED_TIMEOUT
The transaction failed because it was not approved within the time limit.
7
NOT_PROCESSED_YET
The transaction is waiting to be processed by the Custody Infrastructure system.
8
CANCELED
A user or admin canceled the transaction.
9
WAITING_FOR_EXTERNAL_COSIGNER
The transaction needs to be signed by one or more cosigners,
10
CANCELED_GROUP_CHANGED
Deprecated
11
CANCELED_ACCOUNT_APPROVERS_CHANGED
Deprecated
12
REPLACED
For UTXOs, notes if the transaction has been replaced in a "replace by fee" operation
13
CONFIRMED
The transaction has been confirmed on the blockchain (only displayed for Collector and MergeUTXO actions)
14
FAILED_POLICY
The transaction cannot be completed due to policy.
6 - TokenizationConfiguration
Description
This schema describes the configuration details of a tokenization event. The system gets the information from the transaction itself. Not all fields are relevant for every currency type. Keys irrelevant to the transaction will return "null" or not appear.
Below is an example of the schema layout and the datatype of each property. Some keys are only relevant for specific currencies or actions.
The TokenizationConfiguration schema may include any of the following nested objects:
TokenConstants: Click the Constants button below to view details.
TokenizationProperties: Click the Properties button below to view details.
TokenizationCode: Click the Code button below to view details.
TokenConstants:Id: ID of the tokenization constant.
TokenName: Name of the token.
TokenSymbol: Symbol of the token.
InitialSupply: Initial supply of the token.
Decimals: Decimals of the token
TokenizationProperties:IsProxy: Indicates if it is a proxy.
CanBurn: Indicates if it can burn.
CanMint: Indicates if it can mint.
CanPause: Indicates if it can pause.
CanPermitAndAuthorization: Indicates if it can permit and authorize.
RegulationType: Type of regulation. BLOCKLIST = 0, ALLOWLIST = 1, NONE = 2
Master Schema:Id: ID of the tokenization configuration.
TokenConstants: Tokenization constants.
Owner: Owner of the tokenization configuration.
Pauser: Pauser of the tokenization configuration.
EvmNetwork: EVM network currency enum.
TokenizationProperties: Tokenization properties.
TokenizationCode: Tokenization Code.
DataSigningInformation: Data signing information
TokenizationCode:
TokenCode: Code of the token.
TokenAddress: Address of the token.
ProxyCode: Code of the proxy.
ProxyAddress: Address of the proxy.
7 - DataSigningInformation
Description
This schema describes how data was signed in an event. The system gets the information from the transaction itself. Not all fields are relevant for every currency type. Keys irrelevant to the transaction will return "null" or not appear.
Required:
Type
Payload
Signature
Below is an example of the schema layout and the datatype of each property. Some keys are only relevant for specific currencies or actions.
Type: Type of data to sign: 0=PERSONAL_SIGN, 1=SIGN_TYPED_DATA_V1, 2=SIGN_TYPED_DATA_V3, 3=SIGN_TYPED_DATA_V4, 4=RAW_SIGNING
Payload: Payload of the data to sign.
Signature: Signature of the data.
SignatureHint: Hint for the signature.
8 - TransactionToPresentContract
Description
This schema describes the smart contract operation performed. The system gets the information from the transaction itself. Not all fields are relevant for every currency type. Keys irrelevant to the transaction will return "null" or not appear.

The TransactionToPresentContract schema may include the data object nested within. For more details, click the data button below.
Master Schema:
RawHexData: Raw hex data of the contract.
FunctionName: Function name of the contract.
Data: Data of the contract, see "Data"
Language: Language of the contract 0=Solidity, 1=Michaelson
DeployedContractAddress: Deployed contract address.
Data:Parameters: Parameters of the Michelson contract.
ParameterTypesAndValues: Parameter types and values of the Solidity contract.
Full Examples
Below is an example of a webhook response to receiving BTC.
The same general pattern will be followed for other UTXO input transactions, such as BCH.
The first section (from AdditionalDeposit... to Confirmations) shows where on the blockchain the transaction is located and how many confirmations deep the record was at the time the webhook fired.
Destinations includes two objects, each describing a different address that received funds in the transaction. The address book has contact details for the top item, thus we can see the WalletId and WalletName.
Fees shows what was paid for the transaction.
RawTransaction and SourceMemo aren't relevant.
Sources reflects the details of where the transaction originated. The nulls show that this originated from someone for whom we don't have contact information listed.
The final properties detail the currency (Symbol), when the transaction was sent to the network (Timestamp), whether an error was encountered (TransactionErrorInBlock), the format of this webhook return (TransactionFormatVersion), the transaction's unique identifier on chain (TransactionId), and whether the transaction was a deposit into or a withdrawal from your account (Type).
Below is an example of a webhook response to sending BTC.
The same general pattern will be followed for other UTXO output transactions, such as BCH.
Here, AdditionalWithdrawal... is populated. It details that the funds left account 1 (AccountId), from the MPC (Machine: 1), and has been transmitted to the blockchain (StatusId: 4). The initiating user is identified by both UserId and UserName.
The BlockNumber is null and the Confirmations are 0 because this webhook fired as soon as the system sent the transaction. No miner has added it to the blockchain yet.
The Destinations object shows details for the single address to where the BTC was sent. We can tell from the inclusion of values for AccountId and Machine that this transfer is destined to an INTERNAL address.
Fees shows what was paid for the transaction.
The Sources object shows where the transaction originated. For outbound transactions, this block will detail exactly where in your GK8 system the assets originated.
The final properties detail the currency (Symbol), when the transaction was sent to the network (Timestamp), whether an error was encountered (TransactionErrorInBlock), the format of this webhook return (TransactionFormatVersion), the transaction's unique identifier on chain (TransactionId), and whether the transaction was a deposit into or a withdrawal from your account (Type).
Below is an example of a webhook response to receiving ETH.
The same general pattern will be followed for other EVM input transactions, such as Polygon and Avalanche.
The AdditionalDeposit... object indicated that the assets did not originate from a smart contract ( InternalTransaction: false). BlockNumber and Confirmations show where on the blockchain the transaction is located and how many confirmations deep the record was at the time the webhook fired.
The Destinations object shows where the assets are going, with Machine: 0 indicating that they will show up in the Cold Vault (after syncing ETH transactions with the MPC).
The Fees object for EVM transactions is far more detailed than it is for UTXO transactions.
Sources lets you know where the assets are coming from.
The final properties detail the currency (Symbol), when the transaction was sent to the network (Timestamp), whether an error was encountered (TransactionErrorInBlock), the format of this webhook return (TransactionFormatVersion), the transaction's unique identifier on chain (TransactionId), and whether the transaction was a deposit into or a withdrawal from your account (Type).
Below is an example of a webhook response to sending ETH.
The same general pattern will be followed for other EVM output transactions, such as Polygon and Avalanche.
The AdditionalWithdrawal... object indicates that assets were successfully sent from the MPC to the blockchain (Machine:1, StatusId:4). UserId and UserName show who initiated the transaction.
The presence of values for BlockNumber and Confirmations show that the transaction has been validated.
The Destinations object shows where the assets are going, with Machine: 0 indicating that they will show up in the Cold Vault (after syncing ETH transactions with the MPC).
The Fees object for EVM transactions is far more detailed than it is for UTXO transactions.
Sources lets you know where the assets are coming from, here indicating the main MPC wallet.
The final properties detail the currency (Symbol), when the transaction was sent to the network (Timestamp), whether an error was encountered (TransactionErrorInBlock), the format of this webhook return (TransactionFormatVersion), the transaction's unique identifier on chain (TransactionId), and whether the transaction was a deposit into or a withdrawal from your account (Type).
Integer Quick Reference for Webhook v2 Output
Integers are used throughout the webhook output. This section serves as a reference to their meaning.
Type ##Basic Property
Value
Meaning
0
Deposit (input) transaction
1
Withdrawal (output) transaction
Type describes whether the transaction is depositing assets into your account ("Type":0), or withdrawing assets from it ("Type":1).
Type is used as a basic property of the TransactionFormatVersion.v2 output.
There are two different places Type is used in the new webhooks output format, and the value must be interpreted depending on the context in which it appears!
Machine
Value
Meaning
0
Cold Vault
1
MPC
Machine indicates whether the object (either source or destination) is describing the Cold Vault("Machine":0), or the MPC ("Machine":1).
Machine is used in the following schemas:
TransactionToPresentDestination
AdditionalWithdrawalTransactionData
DepositAddressIndex
The DepositAddressIndex is a reference number for deposit addresses. The first deposit address created on a given account is assigned the index value of 1, and each subsequent address is assigned an incrementally higher value.
DepositAddressIndex is used in the TransactionToPresentDestination schema.
StatusId
Status ID
Name
Description
0
APPROVED
Created
1
FAILED_LIMITATIONS
The transaction amount or fees exceed the initiator's limits and cannot be completed.
2
FAILED_TECHNICAL
The transaction has failed due to technical issues.
3
SIGNED
The transaction is signed and ready to transmit to the blockchain.
4
SENT
The transaction has been transmitted to the blockchain.
5
FAILED_NO_FUNDS
The transaction cannot be completed due to a lack of funds in the originating wallet.
6
FAILED_TIMEOUT
The transaction failed because it was not approved within the time limit.
7
NOT_PROCESSED_YET
The transaction is waiting to be processed by the Custody Infrastructure system.
8
CANCELED
A user or admin canceled the transaction.
9
WAITING_FOR_EXTERNAL_COSIGNER
The transaction needs to be signed by one or more cosigners.
10
CANCELED_GROUP_CHANGED
Depricated
11
CANCELED_ACCOUNT_APPROVERS_CHANGED
Depricated
12
REPLACED
For UTXOs, notes if the transaction has been replaced in a "replace by fee" operation
13
CONFIRMED
The transaction has been confirmed on the blockchain (only displayed for Collector and MergeUTXO actions)
14
FAILED_POLICY
The transaction cannot be completed due to policy.
The StatusId describes the state of a transaction at the moment the webhook response was generated.
StatusId is used in the AdditionalWithdrawalTransactionData schema.
Decimals
Each specific cryptocurrency or token is tracked to a certain number of decimal places after the decimal point. For example, BTC is tracked to 8 decimal places while ETH is tracked to 18. Decimals indicates to how many places the currency of the transaction is tracked.
Decimals is used in the TokenConstants object of the TokenizationConfiguration schema.
RegulationType
Value
Meaning
0
Blocklist
1
Allowlist
2
None
RegulationType indicates whether the action being described by the object is actively permitted by an entry on the allowlist, actively blocked by an entry on the blocklist, or is unregulated (none).
RegulationType is used in the TokenizationProperties object of the TokenizationConfiguration schema.
Type ##DataSigningInformation
Value
Meaning
0
PERSONAL_SIGN
1
SIGN_TYPED_DATA_V1
2
SIGN_TYPED_DATA_V3
3
SIGN_TYPED_DATA_V4
4
RAW_SIGNING
This is used when smart contract transactions are signed off-chain. EIP712 signatures are indicated by SIGN_TYPED_DATA_V4.
Type is used in the DataSigningInformation schema.
There are two different places Type is used in the new webhooks output format, and the value must be interpreted depending on the context in which it appears!
Further Reading
Read about how to configure webhooks in the Webhook Usage article.
