Periodic Webhooks

Transactions on blockchains like Ethereum and Bitcoin take time to achieve finality. In blockchain terms, finality refers to the point at which a transaction becomes permanent and irreversible. When receiving a transaction into your wallets, you want to stay updated on the progress of block confirmations, instead of waiting for the final confirmation (See Block confirmations for finalisation block values for different chains) which takes time. As an Exchange, you can notify your customers of the status of their deposits as it proceeds through confirmations on-chain.

To activate periodic webhooks, an organisation must first configure the minimum block confirmation number. This number determines when the first periodic webhook is triggered. After that, webhooks are sent at regular intervals based on the predefined block periodicity of the blockchain.

For example, in Ethereum, if the minimum block confirmation number is set to 2 and the default periodicity is 6, the first webhook is triggered when the transaction reaches the 2nd block confirmation. The second webhook is sent at block 8 (2 + 6), the third at block 14 (8 + 6), the fourth at block 20 (14 + 6), and the final webhook at the last confirmation block, which is 22 for Ethereum.

How to use this feature

• If your customer is depositing funds that you will receive in your deposit wallet, you can use periodic webhooks to update them on the progress.
• If you are receiving funds in your one of your cold or warm wallets regularly from an external wallet, you use periodic webhooks to be updated on the progress.

Set up min block confirmation number and activate periodic webhooks for Bitcoin and Ethereum (including ERC-20 tokens)

In Liminal Vaults, as an organisation, you can configure the minimum block confirmation number to activate periodic webhooks. This number determines when the first periodic webhook is triggered. After that, webhooks are sent at regular intervals based on the predefined block periodicity of the blockchain.

To set up the block confirmation number for webhooks, take the following steps.

1. Log into Vaults.
2. Go to Dev section.
3. Under Webhook, select Settings.

4. Select the blockchain network in the Protocol field.
5. Enter the block number in the Minimum Block Confirmation field to set the block number at which you wish to receive your first periodic webhook confirmation. (We recommend you set 1 for both Ethereum and Bitcoin)
6. Select Save to save the changes.

Refer the table below for default values of periodicity and final confirmation

Default values for periodicity and final confirmation

Currently, Liminal has configured the following default values for periodicity for different chains.

Permissible values for minimum block confirmations

Newly Introduced Transaction Status Object

In Liminal, transactions have legacy, primary, and secondary statuses. Legacy status refers to the earlier convention of transaction status' followed by Liminal depending on the stage of the transaction within Liminal and on-chain.

These are as per the below table

The legacy status is denoted by an integer, like 1, whereas, the primary status is represented by a string, like pending. The sub statuses represent a specific or detailed inner state of the transaction in the process. For example, if a transaction is in the pending state (primary status), the transaction can be awaiting_finalisation (secondary status) or finalised. Eventually a transaction is considered successful and completed.

Refer to the following tables of statuses for transactions received in your webhook response

Updated webhook response

The transactionStatus and blockConfirmationData objects are added to every webhook response. In order to remain backward compatible with the previous json response, the fields txStatus and blockConfirmation have not been updated. The sample webhook response and the description of the fields are given as follows.

{
  "fee": 0.000239770872369,
  "coin": "ETH",
  "txid": "0xb51540ce3bd615c744861e8c6a5f23c10c3c5006c7df87e57cf2571db578cf66",
  "type": "receive",
  "block": 8324149,
  "walletid": "23503",
  "timestamp": "2025-05-14T09:27:32.339Z",
  "wallet_address": "0x570fa11BfFe22061E924dE49742d661A7DF6d17F",
  "effectivechange": 1e-7,
  "externaladdress": "0x69b8826Ae6a06BC33570103b622Bec8CdF90b9EE",
  "effectivechangeusd": 0.00025958118050357,
  "id": 113,
  "wallet": {
    "id": "23503",
    "name": "Product Team withdrawal ETH",
    "type": "mpc",
    "config": "2of2",
    "status": 1,
    "balance": "0.14291555",
    "balanceusd": "370.98187181",
    "raw": null,
    "issynced": true,
    "walletpath": "m/44/60/1/1234/0/0/0",
    "walletidentifier": "0x570fa11BfFe22061E924dE49742d661A7DF6d17F",
    "chain": "ETH",
    "subtype": "hot",
    "coin": "ETH",
    "orgid": 1234,
    "parentchain": "EVM",
    "canInitiatorSign": 1,
    "suspendedStatus": 0,
    "suspendedRemark": null,
    "isArchived": false,
    "teamId": null,
    "version": 1,
    "account": null,
    "orgWebhook": "https://c70a5e1afdb0a586c53ae351815c8f6b.m.pipedream.net/"
  },
  "tokenContractAddress": "",
  "sequenceId": "",
  "explorerLink": "https://sepolia.etherscan.io/tx/0xb51540ce3bd615c744861e8c6a5f23c10c3c5006c7df87e57cf2571db578cf66",
  "inputs": [
    {
      "address": "0x69b8826Ae6a06BC33570103b622Bec8CdF90b9EE",
      "amount": "0.00000000",
      "isMine": false
    }
  ],
  "outputs": [
    {
      "address": "0x570fa11BfFe22061E924dE49742d661A7DF6d17F",
      "amount": "0.00000010",
      "isMine": true,
      "wallet": {
        "id": 23503,
        "name": "Product Team withdrawal ETH",
        "type": "mpc",
        "config": "2of2",
        "status": 1,
        "balance": "0.14291555",
        "balanceusd": "370.98187181",
        "raw": null,
        "issynced": true,
        "walletpath": "m/44/60/1/1234/0/0/0",
        "walletidentifier": "0x570fa11BfFe22061E924dE49742d661A7DF6d17F",
        "chain": "ETH",
        "subtype": "hot",
        "coin": "ETH",
        "orgid": 1234,
        "parentchain": "EVM",
        "canInitiatorSign": 1,
        "suspendedStatus": 0,
        "suspendedRemark": null,
        "isArchived": false,
        "teamId": null,
        "version": 1,
        "account": null
      }
    }
  ],
  "blockConfirmation": 19,
  "transactionStatus": {
    "legacyStatus": 2,
    "primaryStatus": "pending",
    "secondaryStatus": "awaiting_finalisation"
  },
  "blockConfirmationData": {
    "periodicity": 13,
    "block": 8324149,
    "numberOfConfirmations": 19
  },
  "resData": {
    "success": true
  },
  "txStatus": 0
}

Descriptions and example values

legacyStatus: ‘The legacy status of the transaction in number.’
example: 2

primaryStatus: ‘This is the broader stage of the transaction.’
example: pending

secondaryStatus: ‘The specific stage of the transaction.’
example: awaiting_finalisation

periodicity : 'The block number at which the periodic webhook was triggerred.'
example: 13

📘

Note

• The success webhook response will have periodicity value as null.
• Sometimes a periodic webhook might be missed to be sent if the transaction is finalised before we re-read the blockchain. In that case you will directly receive the success/completed webhook.