Deprecated parameters
Deprecated parameters may still appear in webhook payloads for backwards compatibility reasons. However, Fireblocks no longer maintains these parameters and they should not be used.
This page describes all events relating to transactions that produce webhook notifications, and their associated data objects.
The type parameter is automatically set to the description name for the data objects below.
Transaction initiated
A notification is sent when a new transaction is initiated in the workspace.
Webhook data
| Parameter | Type | Description |
|---|---|---|
| type | string | TRANSACTION_CREATED |
| tenantId | string | Unique ID of your Fireblocks' workspace |
| timestamp | number | Timestamp in milliseconds |
| data | TransactionDetails | All the transaction information |
Transaction status updated
A notification is sent when there is any change in a transaction's status or when the number of confirmations is updated.
Webhook data
| Parameter | Type | Description |
|---|---|---|
| type | string | TRANSACTION_STATUS_UPDATED |
| tenantId | string | Unique ID of your Fireblocks' workspace |
| timestamp | number | Timestamp in milliseconds |
| data | TransactionDetails | All the transaction information |
Transaction approval status updated
A notification is sent with every approval based on the Transaction Authorization Policy.
Webhook data
| Parameter | Type | Description |
|---|---|---|
| type | string | TRANSACTION_APPROVAL_STATUS_UPDATED |
| tenantId | string | Unique ID of your Fireblocks' workspace |
| timestamp | number | Timestamp in milliseconds |
| data | TransactionDetails | All the transaction information |
TransactionDetails
| Parameter | Type | Description |
|---|---|---|
| id | string | The ID of the transaction. |
| 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 | 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.[ TRANSFER, MINT, BURN, CONTRACT_CALL, TYPED_MESSAGE, RAW, ENABLE_ASSET, STAKE, UNSTAKE, WITHDRAW] |
| 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 | TransferPeerPathResponse | 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 multi-input UTXO. This parameter is empty in any other case. |
| destination | TransferPeerPathResponse | 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. If the status is CONFIRMING, COMPLETED, or was CONFIRMING before either FAILED or REJECTED this parameter will contain the destination address. This parameter is empty in any other case. |
| 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 that rejected the transaction. Only populated when a transaction is rejected. |
| authorizationInfo | AuthorizationInfo | Data object with information about your Transaction Authorization Policy (TAP). For more about the TAP, refer to the Fireblocks Help Center. |
| exchangeTxId | string | If the transaction originated from an exchange, this is the exchange’s ID of 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. |
| index | number | (Optional) For UTXO-based assets this is the vOut. For EVM-based, this is the index of the event of the contract call. This field is not returned if a transaction uses the destinations object with more than one value. |
| 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 process(es). If this object is returned with data, expect potential delays or incomplete transaction statuses. |
| addressType | string | (Optional) [ ONE_TIME, WHITELISTED] |
| 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 | [TRANSFER, MINT, BURN, CONTRACT_CALL, TYPED_MESSAGE, RAW, ENABLE_ASSET, STAKE, UNSTAKE, WITHDRAW]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.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 that was requested to be transferred. Otherwise, it is the requested amount. This value will always be equal to the amount (number) parameter of TransactionDetails. |
| requestedAmount | string | The amount requested by the user |
| netAmount | string | The net amount of the transaction, after fee deduction |
| amountUSD | string | The USD value of the requested amount |
FeeInfo
| Parameter | Type | Description |
|---|---|---|
| networkFee | string | The fee paid to the network |
| serviceFee | string | The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount) |
TransferPeerPathResponse
| Parameter | Type | Description |
|---|---|---|
| type | string | [ VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, ONE_TIME_ADDRESS, NETWORK_CONNECTION, FIAT_ACCOUNT, GAS_STATION, UNKNOWN ] |
| id | string | The ID of the account to return. Can return as null if the related transaction fails due to a connectivity error. |
| name | string | The name of the account. |
| subType | string | The specific account or wallet. |
Sources and destinations
Learn more about transaction sources and destinations.
DestinationsResponse
| Parameter | Type | Description |
|---|---|---|
| amount | string | The amount to be sent to this destination |
| destination | TransferPeerPathResponse | Destination of the transaction |
| amountUSD | number | The USD value of the requested amount |
| destinationAddress | string | Address where the asset was transferred |
| destinationAddressDescription | string | Description of the address |
| amlScreeningResult | AmlScreeningResult | The result of the AML screening |
| customerRefId | string | 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. |