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

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.

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

Select the blockchain network in the Protocol field.
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.
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.

Chain	Periodicity	Final Confirmation
Ethereum	6	22
Bitcoin	1	2

Permissible values for minimum block confirmations

Chain	Permissible Range
Ethereum	1-15
Bitcoin	1

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

Status	Status Meaning
1	Pending - The transaction is initiated but not yet processed.
2	Broadcasted - The transaction is announced to the network.
4	Confirmed - The transaction is validated and included in the blockchain.
5	Canceled/Failed - The transaction is failed.

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

Stage	legacyStatus	primaryStatus	secondaryStatus
Transaction initiated from external sender and confirmed on chain	2	pending	awaiting_finalisation
Transaction successful	4	successful	completed

Updated webhook response

The transactionStatus and blockConfirmationData objects are added to every webhook response. The sample webhook response and the description of the fields are given as follows.

txStatus:0can be used to distinguish periodic receive webhooks from completed receive webhooks.

In the below sample, the webhook notification setting for min confirmation threshold is set as 1 for Ethereum.

1st block confirmation periodic webhook

{
  "fee": "0.00012432",
  "coin": "USDC",
  "txid": "0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "type": "receive",
  "block": 9755433,
  "walletid": 23504,
  "timestamp": "2025-12-02T20:55:05.789Z",
  "effectivechange": "1.00000000",
  "externaladdress": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
  "effectivechangeusd": "0.99980",
  "id": 11742,
  "wallet": {
    "id": 23504,
    "name": "Product Team deposit ETH 2",
    "type": "mpc",
    "config": "2of2",
    "status": 1,
    "balance": "0.05235432",
    "balanceusd": "156.35303542",
    "raw": null,
    "issynced": true,
    "walletpath": "m/44/60/0/1234/1/0/0",
    "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
    "chain": "ETH",
    "subtype": "deposit",
    "coin": "ETH",
    "orgid": 1234,
    "parentchain": "EVM",
    "canInitiatorSign": 1,
    "suspendedStatus": 0,
    "suspendedRemark": null,
    "isArchived": false,
    "teamId": null,
    "version": 1,
    "updatedAt": "2025-12-02T20:55:05.000Z",
    "account": null,
    "orgWebhook": "https://c70a5e1afdb0a586c53ae351815c8f6b.m.pipedream.net/"
  },
  "tokenContractAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  "sequenceId": "",
  "explorerLink": "https://sepolia.etherscan.io/tx/0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "inputs": [
    {
      "address": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
      "amount": "0.00000000",
      "isMine": false
    }
  ],
  "outputs": [
    {
      "address": "0x4F645fDbE6E0E63194189d6262E6abEF62e7b9C8",
      "amount": "1.00000000",
      "isMine": true,
      "wallet": {
        "id": 23504,
        "name": "Product Team deposit ETH 2",
        "type": "mpc",
        "config": "2of2",
        "status": 1,
        "balance": "0.05235432",
        "balanceusd": "156.35303542",
        "raw": null,
        "issynced": true,
        "walletpath": "m/44/60/0/1234/1/0/0",
        "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
        "chain": "ETH",
        "subtype": "deposit",
        "coin": "ETH",
        "orgid": 1234,
        "parentchain": "EVM",
        "canInitiatorSign": 1,
        "suspendedStatus": 0,
        "suspendedRemark": null,
        "isArchived": false,
        "teamId": null,
        "version": 1,
        "updatedAt": "2025-12-02T20:55:05.000Z",
        "account": null
      }
    }
  ],
  "blockConfirmation": 16,
  "transactionStatus": {
    "legacyStatus": 2,
    "primaryStatus": "pending",
    "secondaryStatus": "awaiting_finalisation"
  },
  "blockConfirmationData": {
    "periodicity": 1,
    "block": 9755433,
    "numberOfConfirmations": 16
  },
  "txStatus": 0
}

7th block confirmation periodic webhook

{
  "fee": "0.00012432",
  "coin": "USDC",
  "txid": "0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "type": "receive",
  "block": 9755433,
  "walletid": 23504,
  "timestamp": "2025-12-02T20:55:05.789Z",
  "effectivechange": "1.00000000",
  "externaladdress": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
  "effectivechangeusd": "0.99980",
  "id": 11742,
  "wallet": {
    "id": 23504,
    "name": "Product Team deposit ETH 2",
    "type": "mpc",
    "config": "2of2",
    "status": 1,
    "balance": "0.05235432",
    "balanceusd": "156.35303542",
    "raw": null,
    "issynced": true,
    "walletpath": "m/44/60/0/1234/1/0/0",
    "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
    "chain": "ETH",
    "subtype": "deposit",
    "coin": "ETH",
    "orgid": 1234,
    "parentchain": "EVM",
    "canInitiatorSign": 1,
    "suspendedStatus": 0,
    "suspendedRemark": null,
    "isArchived": false,
    "teamId": null,
    "version": 1,
    "updatedAt": "2025-12-02T20:55:05.000Z",
    "account": null,
    "orgWebhook": "https://c70a5e1afdb0a586c53ae351815c8f6b.m.pipedream.net/"
  },
  "tokenContractAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  "sequenceId": "",
  "explorerLink": "https://sepolia.etherscan.io/tx/0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "inputs": [
    {
      "address": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
      "amount": "0.00000000",
      "isMine": false
    }
  ],
  "outputs": [
    {
      "address": "0x4F645fDbE6E0E63194189d6262E6abEF62e7b9C8",
      "amount": "1.00000000",
      "isMine": true,
      "wallet": {
        "id": 23504,
        "name": "Product Team deposit ETH 2",
        "type": "mpc",
        "config": "2of2",
        "status": 1,
        "balance": "0.05235432",
        "balanceusd": "156.35303542",
        "raw": null,
        "issynced": true,
        "walletpath": "m/44/60/0/1234/1/0/0",
        "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
        "chain": "ETH",
        "subtype": "deposit",
        "coin": "ETH",
        "orgid": 1234,
        "parentchain": "EVM",
        "canInitiatorSign": 1,
        "suspendedStatus": 0,
        "suspendedRemark": null,
        "isArchived": false,
        "teamId": null,
        "version": 1,
        "updatedAt": "2025-12-02T20:55:05.000Z",
        "account": null
      }
    }
  ],
  "blockConfirmation": 16,
  "transactionStatus": {
    "legacyStatus": 2,
    "primaryStatus": "pending",
    "secondaryStatus": "awaiting_finalisation"
  },
  "blockConfirmationData": {
    "periodicity": 7,
    "block": 9755433,
    "numberOfConfirmations": 16
  },
  "txStatus": 0
}

13th block confirmation periodic webhook

{
  "fee": "0.00012432",
  "coin": "USDC",
  "txid": "0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "type": "receive",
  "block": 9755433,
  "walletid": 23504,
  "timestamp": "2025-12-02T20:55:05.789Z",
  "effectivechange": "1.00000000",
  "externaladdress": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
  "effectivechangeusd": "0.99980",
  "id": 11742,
  "wallet": {
    "id": 23504,
    "name": "Product Team deposit ETH 2",
    "type": "mpc",
    "config": "2of2",
    "status": 1,
    "balance": "0.05235432",
    "balanceusd": "156.35303542",
    "raw": null,
    "issynced": true,
    "walletpath": "m/44/60/0/1234/1/0/0",
    "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
    "chain": "ETH",
    "subtype": "deposit",
    "coin": "ETH",
    "orgid": 1234,
    "parentchain": "EVM",
    "canInitiatorSign": 1,
    "suspendedStatus": 0,
    "suspendedRemark": null,
    "isArchived": false,
    "teamId": null,
    "version": 1,
    "updatedAt": "2025-12-02T20:55:05.000Z",
    "account": null,
    "orgWebhook": "https://c70a5e1afdb0a586c53ae351815c8f6b.m.pipedream.net/"
  },
  "tokenContractAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  "sequenceId": "",
  "explorerLink": "https://sepolia.etherscan.io/tx/0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "inputs": [
    {
      "address": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
      "amount": "0.00000000",
      "isMine": false
    }
  ],
  "outputs": [
    {
      "address": "0x4F645fDbE6E0E63194189d6262E6abEF62e7b9C8",
      "amount": "1.00000000",
      "isMine": true,
      "wallet": {
        "id": 23504,
        "name": "Product Team deposit ETH 2",
        "type": "mpc",
        "config": "2of2",
        "status": 1,
        "balance": "0.05235432",
        "balanceusd": "156.35303542",
        "raw": null,
        "issynced": true,
        "walletpath": "m/44/60/0/1234/1/0/0",
        "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
        "chain": "ETH",
        "subtype": "deposit",
        "coin": "ETH",
        "orgid": 1234,
        "parentchain": "EVM",
        "canInitiatorSign": 1,
        "suspendedStatus": 0,
        "suspendedRemark": null,
        "isArchived": false,
        "teamId": null,
        "version": 1,
        "updatedAt": "2025-12-02T20:55:05.000Z",
        "account": null
      }
    }
  ],
  "blockConfirmation": 16,
  "transactionStatus": {
    "legacyStatus": 2,
    "primaryStatus": "pending",
    "secondaryStatus": "awaiting_finalisation"
  },
  "blockConfirmationData": {
    "periodicity": 13,
    "block": 9755433,
    "numberOfConfirmations": 16
  },
  "txStatus": 0
}

19th block confirmation periodic webhook

In this example, before Liminal read the Ethereum Blockchain at 14th block confirmation. By the time it read the blockchain again 24 blocks had been confirmed. However, for Ethereum 22nd block is considered as the finalisation block. Hence, for this transaction Liminal will directly send the final confirmation (completed, success) webhook instead of the 19th block confirmation periodic webhook.

Final successful and completed webhook

{
  "id": 159609444,
  "txid": "0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "raw": null,
  "walletid": 23504,
  "type": "receive",
  "fee": "0.00012432",
  "effectivechange": "1.00000000",
  "runningbalance": null,
  "timestamp": "2025-12-02T20:55:06.000Z",
  "externaladdress": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
  "block": 9755433,
  "coin": "USDC",
  "effectivechangeusd": "0.99980",
  "createdAt": "2025-12-02T20:59:00.000Z",
  "wallet": {
    "id": 23504,
    "name": "Product Team deposit ETH 2",
    "type": "mpc",
    "config": "2of2",
    "balance": "0.05235432",
    "address": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
    "chain": "ETH",
    "subtype": "deposit",
    "coin": "ETH",
    "orgid": 1234,
    "parentchain": "EVM",
    "isArchived": false,
    "balanceUSD": "156.35303542",
    "orgWebhook": "https://c70a5e1afdb0a586c53ae351815c8f6b.m.pipedream.net/"
  },
  "tokenContractAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  "sequenceId": "",
  "explorerLink": "https://sepolia.etherscan.io/tx/0xfd0ccad29f3734cec4ff03a40119433e4fc8130e8f8241bc09eba74e6cbf610b",
  "inputs": [
    {
      "address": "0x319dd63E0AC72e7Ac74443029d074032c043460F",
      "amount": "0.00000000",
      "isMine": false
    }
  ],
  "outputs": [
    {
      "address": "0x4F645fDbE6E0E63194189d6262E6abEF62e7b9C8",
      "amount": "1.00000000",
      "isMine": true,
      "wallet": {
        "id": 23504,
        "name": "Product Team deposit ETH 2",
        "type": "mpc",
        "config": "2of2",
        "status": 1,
        "balance": "0.05235432",
        "balanceusd": "156.35303542",
        "raw": null,
        "issynced": true,
        "walletpath": "m/44/60/0/1234/1/0/0",
        "walletidentifier": "0xf481D1fF229d8357413aF14727d6D4d22f7eE95B",
        "chain": "ETH",
        "subtype": "deposit",
        "coin": "ETH",
        "orgid": 1234,
        "parentchain": "EVM",
        "canInitiatorSign": 1,
        "suspendedStatus": 0,
        "suspendedRemark": null,
        "isArchived": false,
        "teamId": null,
        "version": 1,
        "updatedAt": "2025-12-02T20:55:05.000Z",
        "account": null
      }
    }
  ],
  "blockConfirmation": 26,
  "transactionStatus": {
    "legacyStatus": 4,
    "primaryStatus": "success",
    "secondaryStatus": "completed"
  },
  "blockConfirmationData": {
    "periodicity": null,
    "block": 9755433,
    "numberOfConfirmations": 26
  },
  "txStatus": 1
}

transactionStatus and blockConfirmationData field descriptions and examples

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.