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.
| Event | Sent when |
|---|---|
wallet.created | An address is created in a vault. |
wallet.monitored | Monitoring starts for an address. |
wallet.unmonitored | Monitoring stops for an address. |
| Field | Meaning |
|---|---|
address | The address, as the network displays it. |
chain | The network, such as ethereum. |
ecosystem | The network family, such as evm. |
derivationPath | The 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>.
| Event | Sent when |
|---|---|
wallet.receiveToken | The address received native currency or tokens. Change returned to a Bitcoin-style address isn't reported as a receipt. |
wallet.sendToken | The address sent native currency or tokens. |
wallet.walletInteraction | The transaction involved the address but moved no value for it, such as a token approval. |
wallet.transactionFailed | The 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.
| Event | Sent when |
|---|---|
transaction.confirmed | The transaction is included in a block. |
transaction.finalized | The 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.reorged | The block containing the transaction was replaced in a reorganisation. |
Transfer and transaction events share these fields:
| Field | Meaning |
|---|---|
address | Your vault's address the event is about. |
chain | The network. |
transactionHash | The transaction hash. |
finality | The transaction's on-chain status when the event was sent: pending, confirmed, finalized, failed, orphaned, or replaced. |
blockNumber | The block number, as a string, once known. |
amount, asset | The amount, as a decimal string, and the asset's symbol. wallet.sendToken and wallet.receiveToken only. |
fromAddress, toAddress | The sender and recipient. wallet.sendToken and wallet.receiveToken only. |
contractAddress | The token contract, for token transfers. wallet.sendToken and wallet.receiveToken only. |
operationId, cryptoTransactionRequestId | The transaction request that sent it, when the transaction came from your vault through Treasury. Not sent on wallet.receiveToken. |
error | Why 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.
| Event | Sent when |
|---|---|
operation.created | A request or operation is created. |
operation.updated | Its 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
| Field | Meaning |
|---|---|
id | The transaction request ID. |
status | The request status, such as submitted_for_signature or broadcast. |
kind | transaction, or signature for a signature-only request. |
chain | The network. |
txHash | The transaction hash, once there is one. |
subStatus | On 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. |
onChainTransaction | On on-chain updates: the transaction's id, txHash, status, settled, blockNumber, confirmedAt, and finalizedAt. |
version | When this state was recorded. Use it to ignore older updates that arrive late. |
type | Always SIGN. Use it to tell a transaction request from a Tokenisation operation. |
Tokenisation operations
| Field | Meaning |
|---|---|
id | The operation ID. |
type | The operation, such as deploy, mint, burn, pause, force-transfer, or allowlist-update. |
status | submitted_for_signature, broadcast, completed, failed, rejected, cancelled, or expired. |
chain, tokenId, contractAddress | The token the operation acts on. Any of these can be null, for example before a token is deployed. |
txHash | The transaction hash, once there is one. |
subStatus | On operation.updated: BROADCAST, MINED, or FAILED. |
subjectAddress | The address a compliance or identity operation acts on, when the operation names one. |
claimTopics | The claim topics an identity claim operation acts on, when the operation names them. |
allowlist | On 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. |
version | When 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.
Updated 3 days ago