Webhook events

Every io.vault event type, when it is sent, and its fields

Every event's data includes vaultId, organisationId, and workspaceId. The tables below list the other fields. Subscribe to events by type, as described in Webhooks.

Address events

Sent by Treasury when a vault address is created or its monitoring changes. subject is the address's ID.

EventSent when
wallet.createdAn address is created in a vault.
wallet.monitoredMonitoring starts for an address.
wallet.unmonitoredMonitoring stops for an address.
FieldMeaning
addressThe address, as the network displays it.
chainThe network, such as ethereum.
ecosystemThe network family, such as evm.
derivationPathThe address's derivation path, or null for the vault's primary address.

Transfer events

Sent by Treasury the first time it records a transaction involving a monitored address. A transaction that touches several of your addresses produces one event for each. subject is <chain>:<transaction hash>:<address>.

EventSent when
wallet.receiveTokenThe address received native currency or tokens. Change returned to a Bitcoin-style address isn't reported as a receipt.
wallet.sendTokenThe address sent native currency or tokens.
wallet.walletInteractionThe transaction involved the address but moved no value for it, such as a token approval.
wallet.transactionFailedThe transaction was included on chain but failed.

Transfer events are sent once for each block that records the transaction. If Treasury later finds the transaction in a different block, you receive transaction.reorged and new transfer events for the new block. The blockNumber and finality of transaction.reorged describe the new block. Deliveries aren't ordered, so the new transfer events can arrive first. When transaction.reorged arrives, replace what you recorded for that transactionHash and address with the new block's details.

Transaction events

Sent by Treasury as a recorded transaction progresses on chain. Same subject as transfer events. transaction.confirmed and transaction.finalized are sent only when a transaction Treasury already recorded changes status. When Treasury first records a transaction, it sends only the transfer event, with finality set to the status at that point. For example, a transaction first recorded as confirmed sends no transaction.confirmed, but can send transaction.finalized when it later becomes final.

EventSent when
transaction.confirmedThe transaction is included in a block.
transaction.finalizedThe transaction is final under the network's rules. Not every transaction that becomes final sends this event, so don't wait for it before you treat a transaction as final. See Address monitoring.
transaction.reorgedThe block containing the transaction was replaced in a reorganisation.

Transfer and transaction events share these fields:

FieldMeaning
addressYour vault's address the event is about.
chainThe network.
transactionHashThe transaction hash.
finalityThe transaction's on-chain status when the event was sent: pending, confirmed, finalized, failed, orphaned, or replaced.
blockNumberThe block number, as a string, once known.
amount, assetThe amount, as a decimal string, and the asset's symbol. wallet.sendToken and wallet.receiveToken only.
fromAddress, toAddressThe sender and recipient. wallet.sendToken and wallet.receiveToken only.
contractAddressThe token contract, for token transfers. wallet.sendToken and wallet.receiveToken only.
operationId, cryptoTransactionRequestIdThe transaction request that sent it, when the transaction came from your vault through Treasury. Not sent on wallet.receiveToken.
errorWhy the transaction failed, when known. wallet.transactionFailed only.

Request events

Sent when a transaction request or Tokenisation operation is created or changes. subject is the request's or operation's ID.

EventSent when
operation.createdA request or operation is created.
operation.updatedIts status changes, it gets a transaction hash, or its transaction is included, finalised, or fails on chain.

These events have two shapes: one for transaction requests and one for Tokenisation operations. Tell them apart by data.type: SIGN is a transaction request, and any other value is a Tokenisation operation. Don't use source: Tokenisation also sends transaction request events, with source set to vault-tokenisation.

Transaction requests

FieldMeaning
idThe transaction request ID.
statusThe request status, such as submitted_for_signature or broadcast.
kindtransaction, or signature for a signature-only request.
chainThe network.
txHashThe transaction hash, once there is one.
subStatusOn operation.updated: BROADCAST when sent, MINED when included or finalised, or FAILED when the request fails or is rejected, or its transaction fails on chain.
onChainTransactionOn on-chain updates: the transaction's id, txHash, status, settled, blockNumber, confirmedAt, and finalizedAt.
versionWhen this state was recorded. Use it to ignore older updates that arrive late.
typeAlways SIGN. Use it to tell a transaction request from a Tokenisation operation.

Tokenisation operations

FieldMeaning
idThe operation ID.
typeThe operation, such as deploy, mint, burn, pause, force-transfer, or allowlist-update.
statussubmitted_for_signature, broadcast, completed, failed, rejected, cancelled, or expired.
chain, tokenId, contractAddressThe token the operation acts on. Any of these can be null, for example before a token is deployed.
txHashThe transaction hash, once there is one.
subStatusOn operation.updated: BROADCAST, MINED, or FAILED.
subjectAddressThe address a compliance or identity operation acts on, when the operation names one.
claimTopicsThe claim topics an identity claim operation acts on, when the operation names them.
allowlistOn operation.updated for a completed allowlist-update on an EVM network: change (add or remove) and entries, each with an address, ownership (owned, unowned, or unknown), and the organisationId that owns it, which is null unless ownership is owned.
versionWhen this state was recorded.

Events io.vault doesn't send

There are no webhooks for balance changes on their own, pending (mempool) transactions, approvals by individual signers, or policy decisions. Vault and signer changes come from io.sign webhooks.


Did this page help you?