Transaction events

This page covers all transaction events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

Transaction event types

To receive a specific event, include its eventType in the webhook’s notification object.

Event type	Data object returned
transaction.created	TransactionDetails
transaction.status.updated	TransactionDetails
transaction.approval_status.updated	TransactionDetails
transaction.network_records.processing_completed	TransactionDetails
transaction.alert.stuck	TransactionAlertPayload

Transaction alert events

Transaction alert events notify you when Fireblocks detects conditions that may require intervention, such as transactions that have stalled due to fee-related issues. Use these events to build automated monitoring and remediation workflows.

transaction.alert.stuck

Triggered when one or more transactions from a vault account and base asset are stuck in the CONFIRMING status on EVM blockchains, indicating potential fee-related issues that may block subsequent transactions.

Example payload

{
  "id": "39067fb9-5212-48e1-9e60-8ff1b326fdce",
  "resourceId": "9074940b-1ef7-4313-b8c0-cb8958ba945c",
  "webhookId": "072422fd-981f-496f-a926-7b506e4f0588",
  "workspaceId": "97535494-a9ff-564c-af19-6946c40ce39b",
  "eventType": "transaction.alert.stuck",
  "createdAt": 1777241007613,
  "data": {
    "issueType": "LOW_FEE_TRANSACTION_DETECTED",
    "severity": "WARNING",
    "description": "2 transactions stuck in CONFIRMING",
    "vaultAccountId": "0",
    "baseAsset": "ETH_TEST5",
    "recommendedAction": {
      "action": "BOOST_TRANSACTION",
      "description": "Speed up the oldest stuck transaction by replacing it with a higher fee.",
      "stuckTxId": "9074940b-1ef7-4313-b8c0-cb8958ba945c"
    },
    "stuckTransactionDetails": {
      "txId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "txHash": "0xabc123...",
      "status": "CONFIRMING"
    },
    "stuckAccountDetails": {
      "blockedTransactionCount": 2,
      "lastCompletedNonce": 24,
      "blocksElapsed": 15,
      "stuckDurationSeconds": 175
    }
  }
}

Data objects

TransactionDetails

Parameter	Type	Description
id	string	The ID of the transaction.
index	integer	[Optional] Fireblocks’ internal identifier for a specific transfer within a transaction. For UTXO-based assets, this field corresponds to the UTXO’s vOut index. For other blockchains, like EVM, Tron, Solana, etc., this field is derived from the sequential position of the event within the transaction’s transfer list. The field is not returned when the transaction includes multiple destinations.
logIndex	integer	Applicable to EVM blockchains only. Represents the EVM log index that indicates the order of the log within the block. This information can be verified directly on the blockchain.
blockchainIndex	string	Blockchain-native transfer identifier showing the transfer’s exact position within the block data (e.g., log entry, trace path, or nested array index). - EVM token transfers: Uses logIndex. - EVM internal transfers: Uses traceAddress (e.g., [0,1,2] → “0_1_2”). - Solana: Refers to the nested instruction position in the instruction array.
externalTxId	string	Unique transaction ID provided by the user. Fireblocks recommends setting an externalTxId for every transaction created to avoid submitting the same transaction twice.
status	string	The current primary status of the transaction. See Primary Transaction Statuses for a detailed list.
subStatus	string	[Optional] See Transaction Substatuses for a detailed list of transaction substatuses.
txHash	string	The hash of this transaction on the blockchain. txHash is only returned for crypto assets (not fiat) when the operation type is not `RAW` or `TYPED_MESSAGE`. This parameter exists if at least one of the following conditions is met: 1. The transaction’s source type is `UNKNOWN`, `WHITELISTED_ADDRESS`, `ONE_TIME_ADDRESS`, `FIAT` or `GAS_STATION`. 2. The transaction’s source type is `VAULT` and the status is CONFIRMING, COMPLETED, or was either status before changing to FAILED or REJECTED. Some transactions with the status BROADCASTING will also include the txHash. 3. The transaction’s source type is `EXCHANGE` and the transaction’s destination type is `VAULT`, and the status is: CONFIRMING, COMPLETED, or was either status before changing to FAILED.
operation	TransactionOperation	The transaction operation type. The default is `TRANSFER`.
note	string	Custom note that describes this transaction in your Fireblocks workspace. This note is not sent to the blockchain.
assetId	string	The ID of the transaction’s asset, for TRANSFER, MINT, BURN, or ENABLE_ASSET operations. See the list of supported assets and their IDs on Fireblocks.
assetType	AssetType	One of the following: XLM_ASSET, XDB_ASSET, TRON_TRC20, SOL_ASSET, HBAR_ERC20, FIAT, ERC721, ERC20, ERC1155, BEP20, BASE_ASSET, ALGO_ASSET
source	SourceTransferPeerPathResponse	The transaction’s source.
sourceAddress	string	If the status is CONFIRMING, COMPLETED, or was CONFIRMING before either FAILED or REJECTED, this parameter will contain only one source address, even if the transaction is a multi-input UTXO. This parameter is empty in any other case.
destination	DestinationTransferPeerPathResponse	The transaction’s destination. If a transaction is sent to multiple destinations, the destinations parameter is used instead.
destinations	Array of DestinationsResponse	For UTXO-based assets. All outputs are specified here.
destinationAddress	string	Address where the asset was transferred. For Multi-destination transactions, this parameter will be empty, and you should refer to the destinations field instead. `destinationAddress` is populated when Fireblocks can determine a single destination address for the transaction (for example, from the transaction request). It is typically available starting from `transaction.created` for single-destination transfers. For multi-destination transactions (where `destinations` is used), `destinationAddress` is empty. In some failure scenarios or before address resolution, this field may also be empty.
destinationAddressDescription	string	Description of the address.
destinationTag	string	[Optional] Destination address tag for Ripple; destination memo for Cosmos, EOS, Luna, Luna Classic, NEM, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers.
amountInfo	AmountInfo	For `TRANSFER` operations. All details of the transfer amount.
treatAsGrossAmount	boolean	When set to `true`, the fee is deducted from the requested amount for transactions initiated from this Fireblocks workspace.
feeInfo	FeeInfo object	Details of the transaction’s fee.
feeCurrency	string	The asset type used to pay the fee (ETH for ERC-20 tokens, BTC for Omni, XLM for Stellar tokens, etc.)
networkRecords	Array of NetworkRecord objects	A transaction in Fireblocks can aggregate several blockchain transactions, typically as part of a contract call. Network records specify all intermediate transactions that took place on the blockchain. For single transactions, this parameter is empty.
createdAt	number	The transaction’s creation date and time. Shown as a Unix timestamp.
lastUpdated	number	The transaction’s last update date and time. Shown as a Unix timestamp.
createdBy	string	User ID of the transaction’s initiator.
signedBy	Array of strings	User ID(s) of the transaction’s signer(s).
rejectedBy	string	User ID of the user who rejected the transaction. Only populated when a transaction is rejected.
authorizationInfo	AuthorizationInfo	Data object with information about your Policies. For more about Policies, refer to the Fireblocks Help Center.
exchangeTxId	string	If the transaction originated from an exchange, this is the exchange’s ID for this transaction.
customerRefId	string	The ID for AML providers to associate the owner of the funds with the transaction.
amlScreeningResult	AmlScreeningResult object	The result of the AML screening.
replacedTxHash	string	The hash of the replaced transaction. Only populated if this is an RBF transaction on an EVM blockchain. Learn more about RBF transactions.
extraParameters	TransactionExtraParameters object	Parameters that are specific to some transaction operation types and blockchain networks.
signedMessages	Array of SignedMessage objects	A list of signed messages returned for raw signing.
numOfConfirmations	number	The number of blockchain confirmations of the transaction. The number will increase until your workspace’s confirmation policy threshold is satisfied.
blockInfo	BlockInfo object	The hash and height of the block in which the transaction was mined. If an outgoing transaction uses the destinations object with more than one value in the array, blockHash is set to null.
paidRent	string	The amount of rent paid in SOL to the destination token account.
blockchainInfo	BlockchainInfo object	`blockchainInfo` is a JSON used to store additional data that is blockchain-specific. For example, in HBAR, it will have the txHash in addition to the txID.
rewardsInfo	RewardsInfo object	This field is relevant only for ALGO transactions. Both srcRewrds and destRewards appear only for vault-to-vault transactions. Otherwise, only your workspace side of the transaction is recorded.
systemMessages	Array of SystemMessageInfo objects	A response from Fireblocks with details about the health of the current processes. If this object is returned with data, expect potential delays or incomplete transaction statuses.
addressType	string	[Optional] Covers all transaction events.
nonce	string	The transaction’s unique, one-time use number.
requestedAmount (Deprecated)	number	The amount requested by the user.
amount (Deprecated)	number	If the transfer is a withdrawal from an exchange, the actual transfer amount; otherwise, the requested amount.
netAmount (Deprecated)	number	The net amount of the transfer, after fee deduction.
amountUSD (Deprecated)	number	The USD value of the requested amount.
serviceFee (Deprecated)	number	The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount).
networkFee (Deprecated)	number	The fee paid to the blockchain network.

TransactionOperation

Parameter	Type	Description
operation	string	Not all operations are available in all workspaces. Contact your account manager to enable additional features. `TRANSFER` - Default. Transfers funds from one account to another. UTXO blockchains allow multi-input and multi-output transfers. All other blockchains allow transfers with one source address and one destination address. `MINT` - Mints new tokens. Supported for Stellar, Ripple, and EVM-based blockchains. Learn more about tokenization on Fireblocks. `BURN` - Burns tokens. Supported for Stellar, Ripple, and EVM-based blockchains. Learn more about tokenization on Fireblocks. `CONTRACT_CALL` - Calls a smart contract method for web3 operations on any EVM blockchain. The Fireblocks development libraries are recommended for building contract call transactions. `TYPED_MESSAGE` - An off-chain message in either Ethereum Personal Message or EIP712 format. Use it to sign specific readable messages that are not actual transactions. Learn more about typed messages. `RAW` - An off-chain message with no predefined format. Use it to sign any message with your private key, including protocols such as blockchains and custom transaction types that are not natively supported by Fireblocks. Learn more about raw signing transactions. `ENABLE_ASSET` - Algorand, DigitalBits, Solana, and Stellar require an on-chain transaction to create an asset wallet and enable the deposit address. This transaction is automatically created when adding assets on these blockchains to a vault account. `STAKE` - Assign assets to a staking pool managed by a staking validator. Learn more about staking transactions and supported blockchains. This transaction is automatically created when performing staking operations. `UNSTAKE` - Remove assets from a staking pool managed by a staking validator. Learn more about staking transactions and supported blockchains. This transaction is automatically created when performing staking operations. `APPROVE` - Approve transactions call an approve function that allows another address to spend tokens on behalf of the signer. Learn more about Approve Transactions here. `WITHDRAW` - Transfer assets from a dedicated staking vault account to another address. Learn more about staking transactions and supported blockchains. This transaction is automatically created when performing staking operations. Note: Fireblocks may rename this type from WITHDRAW to a different name soon. There will be at minimum a 7-day notice regarding the new type name.

AmountInfo

Parameter	Type	Description
amount	string	If the transfer is a withdrawal from an exchange, the actual amount requested to be transferred; otherwise, it is the requested amount.
requestedAmount	string	The amount requested by the user.
netAmount	string	The net amount of the transaction, after fee deduction. A value of -1 indicates the net amount has not yet been determined.
amountUSD	string	The USD value of the requested amount.

transaction_status_updated webhooks contain only up to 17 digits past the decimal place when reporting balances.

FeeInfo

Parameter	Type	Description
fee	string	The total fee charged for the transaction. A value of -1 indicates the fee has not yet been determined.
networkFee	string	The fee paid to the network. A value of -1 indicates the fee has not yet been determined.
serviceFee	string	The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount).
gasPrice	string	The amount of gas required by/paid to the network to process the transaction.
L1networkFee	string	Layer 1 network fee for Layer 2 blockchain transactions.
L2networkFee	string	Layer 2 network fee (gas price component for Layer 2 transactions).
paidByRelay	boolean	Indicates whether the relay paid the fee.
relayType	string	Indicates whether the relay is the same tenant (`LOCAL`) or another tenant (`THIRD_PARTY`).
relayId	string	The Vault account ID of the relay.
relayName	string	The name of the tenant hosting the third-party relay.
feeUSD	string	The USD equivalent value of the fee.

SourceTransferPeerPathResponse

Parameter	Type	Optional	Description
type	string	No	`VAULT_ACCOUNT`, `EXCHANGE_ACCOUNT`, `INTERNAL_WALLET`, `EXTERNAL_WALLET`, `UNMANAGED_WALLET`, `ONE_TIME_ADDRESS`, `NETWORK_CONNECTION`, `FIAT_ACCOUNT`, `GAS_STATION`, `UNKNOWN`, `CONTRACT`, `MULTI_DESTINATION`
id	string	Yes	The ID of the account. Can return as `null` if the related transaction fails due to a connectivity error.
name	string	Yes	The name of the account.
subType	string	Yes	The specific account or wallet type.
walletId	string	Yes	The wallet ID associated with the source.
tradingAccount	string	Yes	For exchange internal transfers, the type of trading account.

For more details, see transaction sources and destinations.

DestinationTransferPeerPathResponse

Parameter	Type	Optional	Description
type	string	No	`VAULT_ACCOUNT`, `EXCHANGE_ACCOUNT`, `INTERNAL_WALLET`, `EXTERNAL_WALLET`, `UNMANAGED_WALLET`, `ONE_TIME_ADDRESS`, `NETWORK_CONNECTION`, `FIAT_ACCOUNT`, `GAS_STATION`, `UNKNOWN`, `CONTRACT`, `MULTI_DESTINATION`
id	string	Yes	The ID of the account. Can return as `null` if the related transaction fails due to a connectivity error.
name	string	Yes	The name of the account.
subType	string	Yes	The specific account or wallet type.
walletId	string	Yes	The wallet ID associated with the destination.
tradingAccount	string	Yes	For exchange internal transfers, the type of trading account.

DestinationsResponse

Parameter	Type	Optional	Description
amount	string	No	The amount to be sent to this destination.
destination	DestinationTransferPeerPathResponse	No	Destination of the transaction.
amountUSD	number	Yes	The USD value of the requested amount.
destinationAddressDescription	string	Yes	Description of the address.
amlScreeningResult	AmlScreeningResult	Yes	The result of the AML screening.
customerRefId	string	Yes	The ID for AML providers to associate the owner of funds with transactions.

TransactionExtraParameters

Parameter	Type	Description
inputsSelection	InputsSelection object	For UTXO-based blockchain multi-input selection, use the `inputsSelection` field with values set to the input selection structure. The inputs can be retrieved using the Retrieve Unspent Inputs endpoint.
rawMessageData	RawMessageData object	For `RAW` operations, use the rawMessageData field with the values set to the raw message data structure. Only included with raw signing transactions on Bitcoin and Ethereum. This is an opt-in feature. Please contact Fireblocks Support to include this feature in your workspace.
contractCallData	string	For `CONTRACT_CALL` operations, use the contractCallData field with the value set to the Ethereum smart contract Application Binary Interface (ABI) payload. The Fireblocks development libraries are recommended for building contract call transactions.

SystemMessageInfo

Parameter	Type	Description
type	string	(`WARN`, `BLOCK`)
message	string	A response from Fireblocks that communicates a message about the health of the process being performed. If this object is returned with data, you should expect potential delays or incomplete transaction statuses.

TransactionAlertPayload

The data object returned with transaction.alert.stuck events.

Field	Type	Description
`issueType`	string	The type of issue detected. Possible values: `LOW_FEE_TRANSACTION_DETECTED`
`severity`	string	Alert severity level. Possible values: `WARNING`, `CRITICAL`
`description`	string	Human-readable description of the issue.
`vaultAccountId`	string	The ID of the affected vault account.
`baseAsset`	string	The base asset of the affected wallet (e.g., `ETH`).
`recommendedAction`	object	The recommended action to resolve the issue. See RecommendedAction.
`stuckTransactionDetails`	StuckTransactionDetails	Details of the stuck head-of-queue transaction.
`stuckAccountDetails`	object	[Optional] Details about the stuck account state. See StuckAccountDetails.

RecommendedAction

Field	Type	Description
`action`	string	The action type. Possible values: `BOOST_TRANSACTION`
`description`	string	Human-readable description of the recommended action.
`stuckTxId`	string	The Fireblocks transaction ID of the oldest stuck transaction to boost.

StuckTransactionDetails

Field	Type	Description
`txId`	string	Fireblocks transaction ID of the stuck head-of-queue transaction.
`txHash`	string \| null	On-chain transaction hash; `null` if not yet broadcast.
`status`	string	Status in which the transaction is stuck. Possible values: `CONFIRMING`

StuckAccountDetails

Field	Type	Description
`blockedTransactionCount`	integer	Number of transactions currently stuck or blocked by the stuck transaction.
`lastCompletedNonce`	integer \| null	The last nonce that completed successfully for this account. `null` if no prior transaction has been completed for this vault account on this chain.
`blocksElapsed`	integer	Number of blocks elapsed since the transaction became stuck.
`stuckDurationSeconds`	integer	Number of seconds the transaction has been stuck.

Get Started

Workspace & Security

Webhooks

Direct Custody Wallets

Manage Wallets

Embedded Wallets

Transactions

Transaction Fees & Gas Station

Treasury & Trading

Smart Contracts & Tokenization

Assets & NFTs

Compliance

Payments

Offchain Signing

API Co-Signers

Integrations

Transaction event types

Transaction alert events

transaction.alert.stuck

Example payload

Data objects

TransactionDetails

TransactionOperation

AmountInfo

FeeInfo

SourceTransferPeerPathResponse

DestinationTransferPeerPathResponse

DestinationsResponse

TransactionExtraParameters

SystemMessageInfo

TransactionAlertPayload

RecommendedAction

StuckTransactionDetails

StuckAccountDetails

​Transaction event types

​Transaction alert events

​transaction.alert.stuck

​Example payload

​Data objects

​TransactionDetails

​TransactionOperation

​AmountInfo

​FeeInfo

​SourceTransferPeerPathResponse

​DestinationTransferPeerPathResponse

​DestinationsResponse

​TransactionExtraParameters

​SystemMessageInfo

​TransactionAlertPayload

​RecommendedAction

​StuckTransactionDetails

​StuckAccountDetails

Transaction event types

Transaction alert events

transaction.alert.stuck

Example payload

Data objects

TransactionDetails

TransactionOperation

AmountInfo

FeeInfo

SourceTransferPeerPathResponse

DestinationTransferPeerPathResponse

DestinationsResponse

TransactionExtraParameters

SystemMessageInfo

TransactionAlertPayload

RecommendedAction

StuckTransactionDetails

StuckAccountDetails