Webhooks API

This page describes the webhook events that Levain sends and their associated data objects.

Wallet

wallet.incoming_deposit

This event is sent when an incoming deposit is detected on a wallet created through Levain. Currently, Levain will send the wallet.incoming_deposit to your webhook:

  • When we first detect the deposit on the blockchain network, in this case confirmed will be false
  • When we subsequently detect the deposit has reached the confirmation policy of the blockchain network, in this case confirmed will be true

Note that due to the nature of blockchain transactions for EVM-based blockchains, you may receive multiple transactions listings in transactions.native, transactions.internal, transactions.erc20 and transactions.trc20.

  • transactions.native will contain the native transactions associated with the deposit transaction, usually these will involve native tokens of a blockchain, if any.
  • transactions.internal will contain the internal transactions associated with the deposit transaction, usually these will involve incoming deposits sent from another contract (e.g. another multi-signature wallet, or using a decentralized exchange's swap and send to another address feature), if any.
  • transactions.erc20 will contain the ERC-20 transactions associated with the deposit transaction, only on EVM-compatible blockchains, if any.
  • transactions.trc20 will contain the TRC-20 transactions associated with the deposit transaction, only on Tron, if any.

We recommend you to rely on webhooks as a form of notifications, and to use the Levain GraphQL API to confirm the status of the deposit.

Parameter Data Type Description
confirmed Boolean Indicates whether the deposit is confirmed, based on the blockchain network's confirmation policy.
eventId String Unique identifier for the event, use this as an idempotent request.
orgId String Organization ID associated with the wallet receiving deposit.
chain String CAIP-2 blockchain identifier.
eventName String wallet.incoming_deposit
block.height Number The block height at which the deposit transaction was included.
block.hash String The hash of the block containing the deposit transaction.
block.timestamp Number The timestamp of the block containing the deposit transaction.
transactions.native Array of LevainWebhookTransactionData Array of native transactions associated with the deposit transaction (if any).
transactions.internal Array of LevainWebhookTransactionData Array of internal transactions (if any).
transactions.erc20 Array of LevainWebhookTransactionData Array of ERC-20 transactions, for EVM-compatible chains only (if any).
transactions.trc20 Array of LevainWebhookTransactionData Array of TRC-20 transactions, for Tron only (if any).
timestamp Number Unix timestamp when the event was generated.

The LevainWebhookTransactionData object contains the following fields:

Parameter Data Type Description
transactionHash String The transaction hash.
fromAddress String The address that sent the transaction.
toAddress String The address that received the transaction.
amount String The formatted amount of the transaction.
tokenSymbol String The token symbol of the transaction, if exists.
contractAddress String The contract address of the transaction, if exists.
rawAmount String The raw amount of the transaction, if exists.

Below is an example of a wallet.incoming_deposit webhook event of a 0.001 ETH native token deposit on Arbitrum Goerli Testnet.

ResponseJSON
{
  "confirmed": true,
  "eventId": "41ce55b9-7349-4a8e-90d4-5f3a2c65c225",
  "eventName": "wallet.incoming_deposit",
  "chain": "caip2:eip155:421613",
  "block": {
    "height": 44143340,
    "hash": "0xa0a5d6e37190a170e6c9d19488a8c59c1046ec04f79bc1150b04b7e6314aff66",
    "timestamp": 1695868685
  },
  "transactions": {
    "native": [
      {
        "transactionHash": "0x457ada6e2a2951f8cb37c16a206e73dd69ef55472a26648273d7a217a23cdac3",
        "fromAddress": "0x34dd9696556fb122222860746f97992dee396296",
        "toAddress": "0xa575c0d4850790a4f032a58c853b52d7e102b2ee",
        "amount": "0.001"
      }
    ],
    "internal": [],
    "erc20": []
  },
  "timestamp": 1695868727467,
  "orgId": "868202983161",
  "webhookId": "82e554a8-e470-4005-9592-b83cfb044c62"
}

Deposit Address

deposit_address.incoming_deposit

This event may be duplicated with wallet.incoming_deposit in certain scenarios, such as when a token is automatically flushed from a deposit address to the wallet's main address in a single transaction. In such a case, you will receive events across both wallet.incoming_deposit and deposit_address.incoming_deposit.

This event is sent when an incoming deposit is detected on a deposit address created through Levain. Currently, Levain will send the deposit_address.incoming_deposit event to your webhook:

  • When we first detect the deposit on the blockchain network, in this case confirmed will be false
  • When we subsequently detect the deposit has reached the confirmation policy of the blockchain network, in this case confirmed will be true

Note that due to the nature of blockchain transactions for EVM-based blockchains, you may receive multiple transactions listings in transactions.native, transactions.internal, transactions.erc20 and transactions.trc20.

  • transactions.native will contain the native transactions associated with the deposit transaction, usually these will involve native tokens of a blockchain, if any.
  • transactions.internal will contain the internal transactions associated with the deposit transaction, usually these will involve incoming deposits sent from another contract (e.g. another multi-signature wallet, or using a decentralized exchange's swap and send to another address feature), if any.
  • transactions.erc20 will contain the ERC-20 transactions associated with the deposit transaction, only on EVM-compatible blockchains, if any.
  • transactions.trc20 will contain the TRC-20 transactions associated with the deposit transaction, only on Tron, if any.

We recommend you to rely on webhooks as a form of notifications, and to use the Levain GraphQL API to confirm the status of the deposit.

Parameter Data Type Description
confirmed Boolean Indicates whether the deposit is confirmed, based on the blockchain network's confirmation policy.
eventId String Unique identifier for the event, use this as an idempotent request.
orgId String Organization ID associated with the wallet receiving deposit.
chain String CAIP-2 blockchain identifier.
eventName String deposit_address.incoming_deposit
block.height Number The block height at which the deposit transaction was included.
block.hash String The hash of the block containing the deposit transaction.
block.timestamp Number The timestamp of the block containing the deposit transaction.
transactions.native Array of LevainWebhookTransactionData Array of native transactions associated with the deposit transaction (if any).
transactions.internal Array of LevainWebhookTransactionData Array of internal transactions (if any).
transactions.erc20 Array of LevainWebhookTransactionData Array of ERC-20 transactions, for EVM-compatible chains only (if any).
transactions.trc20 Array of LevainWebhookTransactionData Array of TRC-20 transactions, for Tron only (if any).
timestamp Number Unix timestamp when the event was generated.

The LevainWebhookTransactionData object contains the following fields:

Parameter Data Type Description
transactionHash String The transaction hash.
fromAddress String The address that sent the transaction.
toAddress String The address that received the transaction.
amount String The formatted amount of the transaction.
tokenSymbol String The token symbol of the transaction, if exists.
contractAddress String The contract address of the transaction, if exists.
rawAmount String The raw amount of the transaction, if exists.

Below is an example of a deposit_address.incoming_deposit webhook event of a 0.001 ETH native token deposit on Arbitrum Goerli Testnet.

ResponseJSON
{
  "confirmed": true,
  "eventId": "41ce55b9-7349-4a8e-90d4-5f3a2c65c225",
  "eventName": "deposit_address.incoming_deposit",
  "chain": "caip2:eip155:421613",
  "block": {
    "height": 44143340,
    "hash": "0xa0a5d6e37190a170e6c9d19488a8c59c1046ec04f79bc1150b04b7e6314aff66",
    "timestamp": 1695868685
  },
  "transactions": {
    "native": [
      {
        "transactionHash": "0x457ada6e2a2951f8cb37c16a206e73dd69ef55472a26648273d7a217a23cdac3",
        "fromAddress": "0x34dd9696556fb122222860746f97992dee396296",
        "toAddress": "0xa575c0d4850790a4f032a58c853b52d7e102b2ee",
        "amount": "0.001"
      }
    ],
    "internal": [],
    "erc20": []
  },
  "timestamp": 1695868727467,
  "orgId": "868202983161",
  "webhookId": "82e554a8-e470-4005-9592-b83cfb044c62"
}