Subscribe to events using webhooks
An event is a notification about any update in a process. In Liminal, events occur when there is an update on the transactions. These real-time updates are notified to you, as a Virtual Asset Service Provider (VASP). This ensures that you are always informed about the confirmation and completion of your customers’ transactions.
The following flowchart illustrates the flow of the webhook and the actions you can take based on them.
The above flowchart is described as in the following steps:
- Your customer (User) initiates a transaction on a blockchain.
- Liminal receives the block confirmation on the transaction.
- Liminal sends a webhook request to your webhook URL.
- You call the Retrieve a transaction status API to check the status of the transaction.
- You validate the API response with the webhook request data.
- If confirmed, you credit your customer’s account.
In Liminal, webhooks are designed to provide real-time updates about two primary types of events – Send (Outgoing Transactions) and Receive (Incoming Transactions).
| Event identification | Description |
|---|---|
| Send | When a transaction is confirmed on the blockchain, for outgoing transactions from Vaults, a 'Send' event is triggered. The associated request notifies your webhook upon the confirmation of the transaction, providing all the necessary details such as transaction ID, the amount sent, the sender's and receiver's wallet details, etc. For more details, see Send webhook requests. |
| Receive | When a transaction is initiated from an external address and the funds are received in an address belonging to a Liminal Wallet, a 'Receive' event occurs. In case of a 'Receive' event the successful confirmation only gets triggered after the transaction is finalised i.e. after sufficient confirmations are received on blockchain as shown in the block confirmation section. For more details, see Receive webhook requests . However, while the transaction is being finalised for Bitcoin, Ether and ERC-20 token transactions on Ethereum, you can subscribe to Periodic webhooks. These periodic webhooks will help you and your customers be updated on the fund deposit status as the transaction progresses through block confirmations on-chain. For more details, see Periodic Webhooks. |
Note
- It is advised to perform the redundancy check upon receiving Liminal webhooks, using the Retrieve a transaction API.
- For batch transfers, a single webhook is triggered with multiple outputs when sending the same native coins to different addresses. If different native coins are sent to different addresses, multiple webhooks are triggered. To see how receive and send webhook payloads look like, check Receive webhook payload for batch transaction and Send webhook payload for batch transaction, respectively.
Block confirmations and Finalisation
Block confirmations play an important role in the security and validity of transactions on the blockchain. In the context of deposits in Liminal, a specific number of block confirmations are required to ensure the validity and confirmation of the transactions. Once these block confirmations are reached the transaction is considered to be finalised. This additional confirmation provides an extra layer of security, reducing the risk of fraudulent transactions.
The following table provides information about the blockchain based block confirmation thresholds for testing and production environments:
| Chain | Block confirmations (testing environment) | Block confirmations (production environment) |
|---|---|---|
| Ethereum | 22 | 22 |
| Binance Smart Chain | NA | 21 |
| Polygon | 20 | 151 |
| Arbitrum | NA | 21 |
| Avalanche | NA | 21 |
| Optimism | NA | 21 |
| Fantom | NA | 21 |
| Flare | NA | 21 |
| Playa3ull | 31 | 31 |
| Bitcoin | 1 | 2 |
| Doge | 20 | 11 |
| Bitcoin Cash | 1 | 10 |
| Litecoin | 1 | 5 |
| Tron | 10 | 31 |
| Solana | 10 | 31 |
| Cardano | 10 | 11 |
| Near | 31 | 31 |
| Algorand | 31 | 31 |
| Gnosis | NA | 21 |
| Xinfin | 10 | 21 |
| Tezos | 30 | NA |
| Base ETH | NA | 50 |
Note
- Ripple, Stellar, and Cosmos networks don't rely on traditional block confirmations. Instead, they use their own consensus protocols where balances and transactions are synced at set intervals.