Webhooks

Webhooks are critical for real-time notifications within our Layer1 platform, enabling automated updates related to payments, conversions, or new address creation events. When such events occur, Layer1 makes an HTTP request to the URL configured by the user for the webhooks.

Acknowledging Webhooks

The Layer1 webhooks service expects to receive a 200 HTTP status code as an acknowledgment of a successfully received and validated webhook. This response should be sent immediately upon receipt of the webhook to confirm its delivery and avoid timeout errors.

Webhook retry policy

If BVNK does not receive a 200 status code, the webhook retry policy will kick in.

The retry policy adds a delay before each retry, starting with a base delay and increasing the time between retries. The delay grows larger after each attempt, but will not exceed 15 minutes. The system will attempt up to 100 times, and after that, no further retries will occur.

Webhook Validation

Webhooks include an x-signature header, which enables servers to authenticate the request using a secret key specific to your server setup.

Signature Calculation with ECDSA

The process to calculate and verify the signature using ECDSA

Capture the raw payload

Do not parse the incoming HTTP request into an object or re-serialize it. Instead, capture the raw payload as a string to ensure that the signature verification process is accurate.

Java

import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.util.encoders.Base64;

import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Security;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;

public class JavaSignatureExample {
  public static void main(String[] args) throws Exception {
    // If you don't already have BouncyCastle as a provider, add it
    if (Security.getProvider(BouncyCastleProvider.PROVIDER_NAME) == null) {
      Security.addProvider(new BouncyCastleProvider());
    }

    // Public key provided from webhook configuration
    String publicKeyBase64 = "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAExn8LhKa3YnVvGHeyT+siyu9+B5knDRtigP4R08nw7Fp0lbXtwoiAO1N0LOj7k39JY5iM385BJrRV2u5Y4N0Qxg==";

    // From X-Signature header
    String signatureBase64 = "MEYCIQCtvKgMTivqsT3S2G3qD46lK0+FD7ECW4dK2MtaivfWvwIhALJly6ZqemabK+gYGNWpZACzj1ApJ6immVuIQ0MxONXV";

    // Body of the request
    String body = "hello world";

    KeyFactory keyFactory = KeyFactory.getInstance("ECDSA", "BC");
    X509EncodedKeySpec publicKeySpec = new X509EncodedKeySpec(Base64.decode(publicKeyBase64));


    PublicKey publicKey = keyFactory.generatePublic(publicKeySpec);

    Signature signature = Signature.getInstance("SHA256withECDSA");
    signature.initVerify(publicKey);

    // The body of the request
    signature.update(body.getBytes());

    boolean verified = signature.verify(Base64.decode(signatureBase64));

    System.out.println("Signature is valid: " + verified);
  }
}

PHP

<?php

function verifyECDSASignatureExample(): bool
{
    // Example data embedded in the function
    $publicKeyBase64 = "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAExn8LhKa3YnVvGHeyT+siyu9+B5knDRtigP4R08nw7Fp0lbXtwoiAO1N0LOj7k39JY5iM385BJrRV2u5Y4N0Qxg==";
    $signatureBase64 = "MEYCIQCtvKgMTivqsT3S2G3qD46lK0+FD7ECW4dK2MtaivfWvwIhALJly6ZqemabK+gYGNWpZACzj1ApJ6immVuIQ0MxONXV";
    $message = "hello world";
    
    try {
        // Decode the base64-encoded public key
        $publicKeyDer = base64_decode($publicKeyBase64);
        if ($publicKeyDer === false) {
            throw new Exception("Failed to decode public key");
        }

        // Create a PEM-formatted public key from the DER data
        $publicKeyPem = "-----BEGIN PUBLIC KEY-----\n" . 
                        chunk_split(base64_encode($publicKeyDer), 64, "\n") . 
                        "-----END PUBLIC KEY-----\n";

        // Load the public key
        $publicKey = openssl_pkey_get_public($publicKeyPem);
        if ($publicKey === false) {
            throw new Exception("Failed to load public key: " . openssl_error_string());
        }

        // Decode the signature
        $signature = base64_decode($signatureBase64);
        if ($signature === false) {
            throw new Exception("Failed to decode signature");
        }

        // Verify the signature
        $result = openssl_verify($message, $signature, $publicKey, OPENSSL_ALGO_SHA256);
        
        // Clean up
        openssl_free_key($publicKey);
        
        if ($result === 1) {
            echo "Signature verification succeeded!\n";
            return true;
        } elseif ($result === 0) {
            echo "Signature verification failed!\n";
            return false;
        } else {
            throw new Exception("Error during signature verification: " . openssl_error_string());
        }
        
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
        return false;
    }
}

// Run the example
verifyECDSASignatureExample();

?>

Python

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
import base64

# Replace this with your webhook public key
public_key_base64 = "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAExn8LhKa3YnVvGHeyT+siyu9+B5knDRtigP4R08nw7Fp0lbXtwoiAO1N0LOj7k39JY5iM385BJrRV2u5Y4N0Qxg=="

# This comes from X-Signature header
signature_base64 = "MEYCIQCtvKgMTivqsT3S2G3qD46lK0+FD7ECW4dK2MtaivfWvwIhALJly6ZqemabK+gYGNWpZACzj1ApJ6immVuIQ0MxONXV"

# This is the body of the request sent to you
message = b"hello world"

# Load the public key from the base64-encoded string
public_key_loaded = serialization.load_der_public_key(
    base64.b64decode(public_key_base64)
)

# Verify the signature using the loaded public key
try:
    public_key_loaded.verify(
        base64.b64decode(signature_base64),
        message,
        ec.ECDSA(hashes.SHA256())
    )
    print("\nSignature verification succeeded!")
except InvalidSignature:
    print("\nSignature verification failed!")

---

Webhook details

For the detailed description of webhooks and their fields, see the Layer1 webhook reference.

Webhooks

layer1:crypto:address:created

The webhook notification sends a JSON object containing details about the event. Here is an example payload:

Address Created

{
  "event": "layer1:crypto:address:created",
  "timestamp": "2024-04-30T15:57:30.399031710Z",
  "data": {
    "id": "37729aed-4e03-46d5-b695-d964da0ae29e",
    "address": "0x157e511931f57d7d41d098b5bebcf8ebfc2b87d8",
    "network": "ETHEREUM",
    "keyPairId": "85cbb05e-8ffe-4b09-ba7d-4c41dfeb551c",
    "reference": "d427cc5f-20d1-4e6d-93b0-454a6cb45cd8",
    "assetPoolId": "e0579d29-987a-440c-b78b-26067b49bc96"
  }
}

Below is a detailed explanation of each field in the webhook payload:

Field	Type	Description
event	string	Identifies the type of event. Example: "layer1:crypto:address:created"
timestamp	string	ISO 8601 formatted date and time when the event was generated.
data	object	Contains detailed information about the event.
data.id	string	Unique identifier for the event, in GUID format.
data.address	string	The cryptocurrency address that was created.
data.network	string	The network for the cryptocurrency address.
data.keyPairId	string	Identifier for the key pair associated with the address, in GUID format.
data.reference	string	A reference identifier linked to the creation of this address, in GUID format.
data.assetPoolId	string	Identifier of the asset pool this address was added to, in GUID format.

---

layer1:crypto:deposit:status-change

The webhook notification sends a JSON object containing details about the event. Here is the example payloads:

Status Change - DETECTED

{
  event: "layer1:crypto:deposit:status-change",
  timestamp: "2024-05-01T11:55:23.676068369Z",
  data: {
    id: "018f3402631176798ab2d431929f53b938d51d4b3ef64c809cb73eb884cc7c306f",
    address: {
      id: "38d51d4b-3ef6-4c80-9cb7-3eb884cc7c30",
      address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
      assetPoolId: "e0579d29-987a-440c-b78b-26067b49bc96",
      network: "ETHEREUM",
      keyPairId: "173cfb47-3ce1-4550-98bc-2da2f1cb866b",
      reference: "fcd4687e-5bc7-41e0-ba5a-d2f13a857ee7",
    },
    reference: null,
    status: "DETECTED",
    sources: [
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.001",
      },
    ],
    destinations: [
      {
        address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
        amount: "0.001",
      },
    ],
    type: "DEPOSIT",
    asset: "ETH",
    amount: "0.001",
    hash: "0x5fee8f91e72d6baba7b95af5a031ea3b3e1ae527009f401b5403a3c2f3294530",
    networkDetail: null,
    metadata: null,
    createdAt: "2024-05-01T11:55:22.769Z",
    updatedAt: "2024-05-01T11:55:23.545773Z",
  },
};

Status Change - UNCONFIRMED

{
  event: "layer1:crypto:deposit:status-change",
  timestamp: "2024-05-01T11:55:28.579411700Z",
  data: {
    id: "018f3402631176798ab2d431929f53b938d51d4b3ef64c809cb73eb884cc7c306f",
    address: {
      id: "38d51d4b-3ef6-4c80-9cb7-3eb884cc7c30",
      address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
      assetPoolId: "e0579d29-987a-440c-b78b-26067b49bc96",
      network: "ETHEREUM",
      keyPairId: "173cfb47-3ce1-4550-98bc-2da2f1cb866b",
      reference: "fcd4687e-5bc7-41e0-ba5a-d2f13a857ee7",
    },
    reference: null,
    status: "UNCONFIRMED",
    sources: [
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.000038485390062",
      },
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.001",
      },
    ],
    destinations: [
      {
        address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
        amount: "0.001",
      },
    ],
    type: "DEPOSIT",
    asset: "ETH",
    amount: "0.001",
    hash: "0x5fee8f91e72d6baba7b95af5a031ea3b3e1ae527009f401b5403a3c2f3294530",
    networkDetail: {
      block: { number: 5814953, timestamp: "2024-05-01T11:55:24Z" },
      fee: { amount: "0.000038485390062", asset: "ETH" },
    },
    metadata: null,
    createdAt: "2024-05-01T11:55:22.769Z",
    updatedAt: "2024-05-01T11:55:28.535125Z",
  },
};

Status Change - CONFIRMED

{
  event: "layer1:crypto:deposit:status-change",
  timestamp: "2024-05-01T11:55:28.579411700Z",
  data: {
    id: "018f3402631176798ab2d431929f53b938d51d4b3ef64c809cb73eb884cc7c306f",
    address: {
      id: "38d51d4b-3ef6-4c80-9cb7-3eb884cc7c30",
      address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
      assetPoolId: "e0579d29-987a-440c-b78b-26067b49bc96",
      network: "ETHEREUM",
      keyPairId: "173cfb47-3ce1-4550-98bc-2da2f1cb866b",
      reference: "fcd4687e-5bc7-41e0-ba5a-d2f13a857ee7",
    },
    reference: null,
    status: "CONFIRMED",
    sources: [
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.000038485390062",
      },
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.001",
      },
    ],
    destinations: [
      {
        address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
        amount: "0.001",
      },
    ],
    type: "DEPOSIT",
    asset: "ETH",
    amount: "0.001",
    hash: "0x5fee8f91e72d6baba7b95af5a031ea3b3e1ae527009f401b5403a3c2f3294530",
    networkDetail: {
      block: { number: 5814953, timestamp: "2024-05-01T11:55:24Z" },
      fee: { amount: "0.000038485390062", asset: "ETH" },
    },
    metadata: null,
    createdAt: "2024-05-01T11:55:22.769Z",
    updatedAt: "2024-05-01T11:55:28.535125Z",
  },
};

Status Change - SCREENING_REQUESTED

{
  event: "layer1:crypto:deposit:status-change",
  timestamp: "2024-05-01T11:56:29.064464799Z",
  data: {
    id: "018f3402631176798ab2d431929f53b938d51d4b3ef64c809cb73eb884cc7c306f",
    address: {
      id: "38d51d4b-3ef6-4c80-9cb7-3eb884cc7c30",
      address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
      assetPoolId: "e0579d29-987a-440c-b78b-26067b49bc96",
      network: "ETHEREUM",
      keyPairId: "173cfb47-3ce1-4550-98bc-2da2f1cb866b",
      reference: "fcd4687e-5bc7-41e0-ba5a-d2f13a857ee7",
    },
    reference: null,
    status: "SCREENING_REQUESTED",
    sources: [
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.000038485390062",
      },
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.001",
      },
    ],
    destinations: [
      {
        address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
        amount: "0.001",
      },
    ],
    type: "DEPOSIT",
    asset: "ETH",
    amount: "0.001",
    hash: "0x5fee8f91e72d6baba7b95af5a031ea3b3e1ae527009f401b5403a3c2f3294530",
    networkDetail: {
      block: { number: 5814953, timestamp: "2024-05-01T11:55:24Z" },
      fee: { amount: "0.000038485390062", asset: "ETH" },
    },
    metadata: null,
    createdAt: "2024-05-01T11:55:22.769Z",
    updatedAt: "2024-05-01T11:56:28.994764Z",
  },
};

Status Change - SUCCESS

{
  event: "layer1:crypto:deposit:status-change",
  timestamp: "2024-05-01T11:56:36.625504360Z",
  data: {
    id: "018f3402631176798ab2d431929f53b938d51d4b3ef64c809cb73eb884cc7c306f",
    address: {
      id: "38d51d4b-3ef6-4c80-9cb7-3eb884cc7c30",
      address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
      assetPoolId: "e0579d29-987a-440c-b78b-26067b49bc96",
      network: "ETHEREUM",
      keyPairId: "173cfb47-3ce1-4550-98bc-2da2f1cb866b",
      reference: "fcd4687e-5bc7-41e0-ba5a-d2f13a857ee7",
    },
    reference: null,
    status: "SUCCESS",
    sources: [
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.000038485390062",
      },
      {
        address: "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        amount: "0.001",
      },
    ],
    destinations: [
      {
        address: "0xf6483454996bce404d62656eb3cbcf87232dc153",
        amount: "0.001",
      },
    ],
    type: "DEPOSIT",
    asset: "ETH",
    amount: "0.001",
    hash: "0x5fee8f91e72d6baba7b95af5a031ea3b3e1ae527009f401b5403a3c2f3294530",
    networkDetail: {
      block: { number: 5814953, timestamp: "2024-05-01T11:55:24Z" },
      fee: { amount: "0.000038485390062", asset: "ETH" },
    },
    metadata: null,
    createdAt: "2024-05-01T11:55:22.769Z",
    updatedAt: "2024-05-01T11:56:36.513590Z",
  },
};

Below is a detailed explanation of each field in the webhook payload:

Field	Type	Description
event	string	Identifies the type of event. Example: "layer1:crypto:deposit:status-change"
timestamp	string	ISO 8601 formatted date and time when the event was generated.
data	object	Contains detailed information about the event.
data.id	string	Unique identifier for the event.
data.address	object	Detailed information about the address involved in the deposit.
data.address.id	string	Unique identifier for the address object, in GUID format.
data.address.address	string	The cryptocurrency address involved.
data.address.assetPoolId	string	Identifier of the asset pool this address belongs to, in GUID format.
data.address.network	string	The network for the cryptocurrency address
data.address.keyPairId	string	Identifier for the key pair associated with the address, in GUID format.
data.address.reference	string	A reference identifier linked to the creation of this address.
data.reference	null/string	A general reference identifier, can be null.
data.status	string	Current status of the deposit [DETECTED, UNCONFIRMED, CONFIRMED, SCREENING_REQUESTED, SUCCESS].
data.sources[]	array	Array of source addresses and amounts involved in the transaction.
data.destinations[]	array	Array of destination addresses and amounts involved in the transaction.
data.type	string	Type of transaction.
data.asset	string	Type of asset involved in the transaction.
data.amount	string	Amount of the asset involved in the transaction.
data.hash	string	Transaction hash.
data.networkDetail	null	Additional network-specific details, can be null.
data.metadata	null	Additional metadata related to the event, can be null.
data.createdAt	string	ISO 8601 formatted date and time when the data was created.
data.updatedAt	string	ISO 8601 formatted date and time when the data was last updated.

---

layer1:crypto:withdrawal:status-change

The webhook notification sends a JSON object containing details about the event. Here is the example payloads:

Status Changed - CREATED

{
  "event": "layer1:crypto:withdrawal:status-change",
  "timestamp": "2024-05-01T14:58:57.756642777Z",
  "data": {
    "id": "018f34aa753176e1a746377665057346aa2eadaf62374e3fb43529de7c4be91969",
    "address": {
      "id": "aa2eadaf-6237-4e3f-b435-29de7c4be919",
      "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
      "assetPoolId": "e0579d29-987a-440c-b78b-26067b49bc96",
      "network": "ETHEREUM",
      "keyPairId": "a2dabc1a-9b36-40dd-b236-2e542fec155c",
      "reference": "085aa928-01b6-407b-82d8-2b9975cbc250"
    },
    "reference": "28b262d9-1f52-4ee2-9f94-addd9762d23c",
    "status": "CREATED",
    "sources": [
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.000117806730763928"
      },
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.001"
      }
    ],
    "destinations": null,
    "type": "WITHDRAWAL",
    "asset": "ETH",
    "amount": "0.001",
    "hash": null,
    "networkDetail": null,
    "metadata": null,
    "createdAt": "2024-05-01T14:58:57.457Z",
    "updatedAt": "2024-05-01T14:58:57.736442Z"
  }
}

Status Changed - SIGNED

{
  "event": "layer1:crypto:withdrawal:status-change",
  "timestamp": "2024-05-01T14:58:58.491311736Z",
  "data": {
    "id": "018f34aa753176e1a746377665057346aa2eadaf62374e3fb43529de7c4be91966",
    "address": {
      "id": "aa2eadaf-6237-4e3f-b435-29de7c4be919",
      "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
      "assetPoolId": "e0579d29-987a-440c-b78b-26067b49bc96",
      "network": "ETHEREUM",
      "keyPairId": "a2dabc1a-9b36-40dd-b236-2e542fec155c",
      "reference": "085aa928-01b6-407b-82d8-2b9975cbc250"
    },
    "reference": "28b262d9-1f52-4ee2-9f94-addd9762d23c",
    "status": "SIGNED",
    "sources": [
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.000117806730763928"
      },
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.001"
      }
    ],
    "destinations": null,
    "type": "WITHDRAWAL",
    "asset": "ETH",
    "amount": "0.000117806730763928",
    "hash": null,
    "networkDetail": null,
    "metadata": null,
    "createdAt": "2024-05-01T14:58:57.457Z",
    "updatedAt": "2024-05-01T14:58:58.366656Z"
  }
}

Status Changed - UNCONFIRMED

{
  "event": "layer1:crypto:withdrawal:status-change",
  "timestamp": "2024-05-01T14:59:02.359359108Z",
  "data": {
    "id": "018f34aa753176e1a746377665057346aa2eadaf62374e3fb43529de7c4be91969",
    "address": {
      "id": "aa2eadaf-6237-4e3f-b435-29de7c4be919",
      "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
      "assetPoolId": "e0579d29-987a-440c-b78b-26067b49bc96",
      "network": "ETHEREUM",
      "keyPairId": "a2dabc1a-9b36-40dd-b236-2e542fec155c",
      "reference": "085aa928-01b6-407b-82d8-2b9975cbc250"
    },
    "reference": "28b262d9-1f52-4ee2-9f94-addd9762d23c",
    "status": "UNCONFIRMED",
    "sources": [
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.000114500286264"
      },
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.001"
      }
    ],
    "destinations": [
      {
        "address": "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        "amount": "0.001"
      }
    ],
    "type": "WITHDRAWAL",
    "asset": "ETH",
    "amount": "0.001",
    "hash": "0xb0d49a30ebe1c84e89a89c52579ae06639dc22d39fd8bb91bfa6dc0130bd09ae",
    "networkDetail": {
      "block": {
        "number": 5815735,
        "timestamp": "2024-05-01T14:59:00Z"
      },
      "fee": {
        "amount": "0.000114500286264",
        "asset": "ETH"
      }
    },
    "metadata": null,
    "createdAt": "2024-05-01T14:58:57.457Z",
    "updatedAt": "2024-05-01T14:59:02.331458Z"
  }
}

Status Changed - CONFIRMED

{
  "event": "layer1:crypto:withdrawal:status-change",
  "timestamp": "2024-05-01T14:59:50.096614363Z",
  "data": {
    "id": "018f34aa753176e1a746377665057346aa2eadaf62374e3fb43529de7c4be91966",
    "address": {
      "id": "aa2eadaf-6237-4e3f-b435-29de7c4be919",
      "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
      "assetPoolId": "e0579d29-987a-440c-b78b-26067b49bc96",
      "network": "ETHEREUM",
      "keyPairId": "a2dabc1a-9b36-40dd-b236-2e542fec155c",
      "reference": "085aa928-01b6-407b-82d8-2b9975cbc250"
    },
    "reference": "28b262d9-1f52-4ee2-9f94-addd9762d23c",
    "status": "CONFIRMED",
    "sources": [
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.000114500286264"
      },
      {
        "address": "0x2ec9ded3d63d2d9c30b72c31d267e207d7242394",
        "amount": "0.001"
      }
    ],
    "destinations": [
      {
        "address": "0xae9e8a1235e1113f936a38492c70fbb4ee297cdb",
        "amount": "0.001"
      }
    ],
    "type": "WITHDRAWAL",
    "asset": "ETH",
    "amount": "0.000114500286264",
    "hash": "0xb0d49a30ebe1c84e89a89c52579ae06639dc22d39fd8bb91bfa6dc0130bd09ae",
    "networkDetail": {
      "block": {
        "number": 5815735,
        "timestamp": "2024-05-01T14:59:00Z"
      },
      "fee": {
        "amount": "0.000114500286264",
        "asset": "ETH"
      }
    },
    "metadata": null,
    "createdAt": "2024-05-01T14:58:57.457Z",
    "updatedAt": "2024-05-01T14:59:50.060099Z"
  }
}

Below is a detailed explanation of each field in the webhook payload:

Field	Type	Description
event	string	Identifies the type of event, for example, "layer1:crypto:withdrawal:status-change"
timestamp	string	ISO 8601 formatted date and time when the event was generated.
data	object	Contains detailed information about the event.
data.id	string	Unique identifier for the event.
data.address	object	Details of the address involved in the withdrawal.
data.address.id	string	Unique identifier for the address object.
data.address.address	string	The cryptocurrency address involved.
data.address.assetPoolId	string	Identifier of the asset pool this address belongs to, in GUID format.
data.address.network	string	The network for the cryptocurrency address.
data.address.keyPairId	string	Identifier for the key pair associated with the address, in GUID format.
data.address.reference	string	A reference identifier linked to the address.
data.reference	string	A general reference identifier for the withdrawal.
data.status	string	Current status of the withdrawal [CREATED, SIGNED,UNCONFIRMED, CONFIRMED].
data.sources[]	array	Array of source addresses and amounts involved in the withdrawal.
data.destinations[]	array	Array of destination addresses and amounts being transferred.
data.type	string	Type of transaction.
data.asset	string	Type of asset involved in the transaction.
data.amount	string	Total amount of the asset being withdrawn.
data.hash	string	Transaction hash.
data.networkDetail	object	Additional details about the network state at the time of the transaction.
data.networkDetail.block	object	Block information relevant to the transaction.
data.networkDetail.block.number	string	Block number associated with the transaction.
data.networkDetail.block.timestamp	string	Timestamp of the block.
data.networkDetail.fee	object	Fee information related to the transaction.
data.networkDetail.fee.amount	string	Amount of the fee charged.
data.networkDetail.fee.asset	string	Asset type of the fee (for example, ETH).
data.metadata	null	Additional metadata related to the event (if any).
data.createdAt	string	ISO 8601 formatted date and time when the data was created.
data.updatedAt	string	ISO 8601 formatted date and time when the data was last updated.

---

layer1:crypto:consolidation:status-change

The webhook notification sends a JSON object containing details about the event. Here is an example payload:

Status Changed - CREATED

{
  "event": "layer1:crypto:consolidation:status-change",
  "timestamp": "2024-05-09T06:11:13.976035981Z",
  "data": {
    "id": "018f5bfa2e9a74edbcbb60fccbe7e842a4e464fb30554fe2a5cb4ed39a14408969",
    "address": {
      "id": "a4e464fb-3055-4fe2-a5cb-4ed39a144089",
      "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
      "assetPoolId": "b85cdc60-29da-4b2a-b28c-248e38cef764",
      "network": "ETHEREUM",
      "keyPairId": "59d0e545-2985-46c2-a834-7ab5199abbd4",
      "reference": "REF-127558124LT181Y1I"
    },
    "reference": "consolidation-018f5bf8-f9c3-77bb-abc7-0b0597001ba1",
    "status": "CREATED",
    "sources": [
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "0.00050889650541582",
        "asset": "ETH"
      },
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "destinations": [
      {
        "address": "0xd399fe8c3914c9dc9f218c912c264d616e32a5ab",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "type": "CONSOLIDATION",
    "asset": "USDT",
    "amount": "100.00",
    "createdAt": "2024-05-09T06:11:13.690Z",
    "updatedAt": "2024-05-09T06:11:13.958481Z"
  }
}

Status Changed - SIGNED

{
  "event": "layer1:crypto:consolidation:status-change",
  "timestamp": "2024-05-09T06:11:14.208226824Z",
  "data": {
    "id": "018f5bfa2e9a74edbcbb60fccbe7e842a4e464fb30554fe2a5cb4ed39a14408969",
    "address": {
      "id": "a4e464fb-3055-4fe2-a5cb-4ed39a144089",
      "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
      "assetPoolId": "b85cdc60-29da-4b2a-b28c-248e38cef764",
      "network": "ETHEREUM",
      "keyPairId": "59d0e545-2985-46c2-a834-7ab5199abbd4",
      "reference": "REF-127558124LT181Y1I"
    },
    "reference": "consolidation-018f5bf8-f9c3-77bb-abc7-0b0597001ba1",
    "status": "SIGNED",
    "sources": [
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "0.00050889650541582",
        "asset": "ETH"
      },
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "destinations": [
      {
        "address": "0xd399fe8c3914c9dc9f218c912c264d616e32a5ab",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "type": "CONSOLIDATION",
    "asset": "USDT",
    "amount": "100.00",
    "createdAt": "2024-05-09T06:11:13.690Z",
    "updatedAt": "2024-05-09T06:11:14.188735Z"
  }
}

Status Changed - DETECTED

{
  "event": "layer1:crypto:consolidation:status-change",
  "timestamp": "2024-05-09T06:11:14.747080547Z",
  "data": {
    "id": "018f5bfa2e9a74edbcbb60fccbe7e842a4e464fb30554fe2a5cb4ed39a14408969",
    "address": {
      "id": "a4e464fb-3055-4fe2-a5cb-4ed39a144089",
      "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
      "assetPoolId": "b85cdc60-29da-4b2a-b28c-248e38cef764",
      "network": "ETHEREUM",
      "keyPairId": "59d0e545-2985-46c2-a834-7ab5199abbd4",
      "reference": "REF-127558124LT181Y1I"
    },
    "reference": "consolidation-018f5bf8-f9c3-77bb-abc7-0b0597001ba1",
    "status": "DETECTED",
    "sources": [
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "100.00"
      }
    ],
    "destinations": [
      {
        "address": "0xd399fe8c3914c9dc9f218c912c264d616e32a5ab",
        "amount": "100.00"
      }
    ],
    "type": "CONSOLIDATION",
    "asset": "USDT",
    "amount": "100.00",
    "hash": "0x74b832f44c3405846bd9a881feca9f9903bf78cca42d5706bc1cec6bc7871685",
    "createdAt": "2024-05-09T06:11:13.690Z",
    "updatedAt": "2024-05-09T06:11:14.726244Z"
  }
}

Status Changed - UNCONFIRMED

{
  "event": "layer1:crypto:consolidation:status-change",
  "timestamp": "2024-05-09T06:11:29.376821677Z",
  "data": {
    "id": "018f5bfa2e9a74edbcbb60fccbe7e842a4e464fb30554fe2a5cb4ed39a14408969",
    "address": {
      "id": "a4e464fb-3055-4fe2-a5cb-4ed39a144089",
      "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
      "assetPoolId": "b85cdc60-29da-4b2a-b28c-248e38cef764",
      "network": "ETHEREUM",
      "keyPairId": "59d0e545-2985-46c2-a834-7ab5199abbd4",
      "reference": "REF-127558124LT181Y1I"
    },
    "reference": "consolidation-018f5bf8-f9c3-77bb-abc7-0b0597001ba1",
    "status": "UNCONFIRMED",
    "sources": [
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "0.00023986962523329",
        "asset": "ETH"
      },
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "destinations": [
      {
        "address": "0xd399fe8c3914c9dc9f218c912c264d616e32a5ab",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "type": "CONSOLIDATION",
    "asset": "USDT",
    "amount": "100.00",
    "hash": "0x74b832f44c3405846bd9a881feca9f9903bf78cca42d5706bc1cec6bc7871685",
    "networkDetail": {
      "block": {
        "number": 5865626,
        "timestamp": "2024-05-09T06:11:24Z"
      },
      "fee": {
        "amount": "0.00023986962523329",
        "asset": "ETH"
      }
    },
    "createdAt": "2024-05-09T06:11:13.690Z",
    "updatedAt": "2024-05-09T06:11:29.352098Z"
  }
}

Status Changed - CONFIRMED

{
  "event": "layer1:crypto:consolidation:status-change",
  "timestamp": "2024-05-09T06:12:29.567534241Z",
  "data": {
    "id": "018f5bfa2e9a74edbcbb60fccbe7e842a4e464fb30554fe2a5cb4ed39a14408969",
    "address": {
      "id": "a4e464fb-3055-4fe2-a5cb-4ed39a144089",
      "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
      "assetPoolId": "b85cdc60-29da-4b2a-b28c-248e38cef764",
      "network": "ETHEREUM",
      "keyPairId": "59d0e545-2985-46c2-a834-7ab5199abbd4",
      "reference": "REF-127558124LT181Y1I"
    },
    "reference": "consolidation-018f5bf8-f9c3-77bb-abc7-0b0597001ba1",
    "status": "CONFIRMED",
    "sources": [
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "100.00",
        "asset": "USDT"
      },
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "0.00023986962523329",
        "asset": "ETH"
      }
    ],
    "destinations": [
      {
        "address": "0xd399fe8c3914c9dc9f218c912c264d616e32a5ab",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "type": "CONSOLIDATION",
    "asset": "USDT",
    "amount": "100.00",
    "hash": "0x74b832f44c3405846bd9a881feca9f9903bf78cca42d5706bc1cec6bc7871685",
    "networkDetail": {
      "block": {
        "number": 5865626,
        "timestamp": "2024-05-09T06:11:24Z"
      },
      "fee": {
        "amount": "0.00023986962523329",
        "asset": "ETH"
      }
    },
    "createdAt": "2024-05-09T06:11:13.690Z",
    "updatedAt": "2024-05-09T06:12:29.545914Z"
  }
}

Status Changed - SUCCESS

{
  "event": "layer1:crypto:consolidation:status-change",
  "timestamp": "2024-05-09T06:12:29.702705023Z",
  "data": {
    "id": "018f5bfa2e9a74edbcbb60fccbe7e842a4e464fb30554fe2a5cb4ed39a14408969",
    "address": {
      "id": "a4e464fb-3055-4fe2-a5cb-4ed39a144089",
      "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
      "assetPoolId": "b85cdc60-29da-4b2a-b28c-248e38cef764",
      "network": "ETHEREUM",
      "keyPairId": "59d0e545-2985-46c2-a834-7ab5199abbd4",
      "reference": "REF-127558124LT181Y1I"
    },
    "reference": "consolidation-018f5bf8-f9c3-77bb-abc7-0b0597001ba1",
    "status": "SUCCESS",
    "sources": [
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "100.00",
        "asset": "USDT"
      },
      {
        "address": "0x1bade4a7ab3f43ef98ee90045d72f70031904c84",
        "amount": "0.00023986962523329",
        "asset": "ETH"
      }
    ],
    "destinations": [
      {
        "address": "0xd399fe8c3914c9dc9f218c912c264d616e32a5ab",
        "amount": "100.00",
        "asset": "USDT"
      }
    ],
    "type": "CONSOLIDATION",
    "asset": "USDT",
    "amount": "100.00",
    "hash": "0x74b832f44c3405846bd9a881feca9f9903bf78cca42d5706bc1cec6bc7871685",
    "networkDetail": {
      "block": {
        "number": 5865626,
        "timestamp": "2024-05-09T06:11:24Z"
      },
      "fee": {
        "amount": "0.00023986962523329",
        "asset": "ETH"
      }
    },
    "createdAt": "2024-05-09T06:11:13.690Z",
    "updatedAt": "2024-05-09T06:12:29.680325Z"
  }
}

Below is a detailed explanation of each field in the webhook payload:

Field	Type	Description
event	string	Identifies the type of event, for example, "layer1:crypto:consolidation:status-change"
timestamp	string	ISO 8601 formatted date and time when the event was generated.
data	object	Contains detailed information about the event.
data.id	string	Unique identifier for the event.
data.address	object	Details of the address involved in the consolidation.
data.address.id	string	Unique identifier for the address object.
data.address.address	string	The cryptocurrency address involved.
data.address.assetPoolId	string	Identifier of the asset pool this address belongs to, in GUID format.
data.address.network	string	The network for the cryptocurrency address.
data.address.keyPairId	string	Identifier for the key pair associated with the address, in GUID format.
data.address.reference	string	A reference identifier linked to the address.
data.reference	string	A general reference identifier for the consolidation event.
data.status	string	Current status of the consolidation [CREATED, SIGNED, DETECTED, UNCONFIRMED, CONFIRMED, SUCCESS].
data.sources[]	array	Array of source addresses and amounts involved in the consolidation.
data.sources[].address	string	The source address involved in the transaction.
data.sources[].amount	string	The amount of the asset being transferred from the source address.
data.sources[].asset	string	Type of asset being transferred.
data.destinations[]	array	Array of destination addresses and amounts being transferred.
data.destinations[].address	string	The destination address involved in the transaction.
data.destinations[].amount	string	The amount of the asset being transferred to the destination address.
data.destinations[].asset	string	Type of asset being transferred.
data.type	string	Type of transaction.
data.asset	string	Type of asset involved in the transaction.
data.amount	string	Total amount of the asset being consolidated.
data.hash	string	Transaction hash.
data.networkDetail	object	Additional details about the network state at the time of the transaction.
data.networkDetail.block	object	Block information relevant to the transaction.
data.networkDetail.block.number	string	Block number associated with the transaction.
data.networkDetail.block.timestamp	string	Timestamp of the block.
data.networkDetail.fee	object	Fee information related to the transaction.
data.networkDetail.fee.amount	string	Amount of the fee charged.
data.networkDetail.fee.asset	string	Asset type of the fee.
data.createdAt	string	ISO 8601 formatted date and time when the data was created.
data.updatedAt	string	ISO 8601 formatted date and time when the data was last updated.

---

layer1:trade:conversion:created

The webhook notification sends a JSON object containing details about the event. Here is an example payload:

Conversion - CREATED

{
  "event": "layer1:trade:conversion:created",
  "timestamp": null,
  "data": {
    "id": "65a726c7-e56f-4bf0-b65e-7225d8abd9ee",
    "reference": "13963121-6626-4694-8fb8-9557db7b5a04",
    "status": "PENDING",
    "from": {
      "asset": "EUR",
      "amount": 100
    },
    "to": {
      "asset": "LTC",
      "amount": 1.386770212175842462
    },
    "orders": null,
    "router": "VWAP",
    "executor": "MAKER",
    "movements": null,
    "createdAt": null
  }
}

Below is a detailed explanation of each field in the webhook payload:

Field	Type	Description
event	string	Identifies the type of event, for example, "layer1:trade:conversion:created".
timestamp	null	The time when the event was generated, can be null.
data	object	Contains detailed information about the event.
data.id	string	Unique identifier for the conversion event, in GUID format.
data.reference	string	A reference identifier linked to the conversion, in GUID format.
data.status	string	Current status of the conversion a the time of creation.
data.from	object	Details about the currency from which is converted.
data.from.asset	string	Type of asset being converted from.
data.from.amount	number	Amount of the asset being converted.
data.to	object	Details about the currency to which is converted.
data.to.asset	string	Type of asset being converted to.
data.to.amount	number	Amount of the asset after conversion.
data.orders	null	Details of any orders involved in the conversion, can be null.
data.router	string	Routing mechanism used for the conversion [VWAP].
data.executor	string	Execution type for the conversion [MAKER].
data.movements	null	Any movements related to the conversion, can be null.
data.createdAt	null	The time when the conversion was created, can be null.

---

layer1:trade:conversion:state-changed

The webhook notification sends a JSON object containing details about the event. Here is the example payloads:

State Changed - PLACED

{
  "event": "layer1:trade:conversion:state-changed",
  "timestamp": "2024-05-01T14:49:43.151138Z",
  "data": {
    "id": "65a726c7-e56f-4bf0-b65e-7225d8abd9ee",
    "reference": "13963121-6626-4694-8fb8-9557db7b5a04",
    "status": "PLACED",
    "from": {
      "asset": "EUR",
      "amount": 100
    },
    "to": {
      "asset": "LTC",
      "amount": 1.386770212175842462
    },
    "orders": [
      {
        "symbol": "LTC-EUR",
        "side": "BUY",
        "targetPrice": 72.11,
        "targetQuantity": 1.386770212175842462,
        "venue": "kraken",
        "output": 0,
        "id": "234098b4-f55b-4ef6-9ea3-1d28010d8476",
        "venueOrderId": "cd5009ad-ecd4-438a-813c-7608c85833d7",
        "status": "PLACED",
        "actualPrice": 0,
        "actualQuantity": 0,
        "createdAt": "2024-05-01T14:49:43.157286Z"
      }
    ],
    "router": "VWAP",
    "executor": "MAKER",
    "movements": [],
    "createdAt": "2024-05-01T14:49:43.151138Z"
  }
}

State Changed - COMPLETE

{
  "event": "layer1:trade:conversion:state-changed",
  "timestamp": "2024-05-01T14:49:43.151138Z",
  "data": {
    "id": "65a726c7-e56f-4bf0-b65e-7225d8abd9ee",
    "reference": "13963121-6626-4694-8fb8-9557db7b5a04",
    "status": "COMPLETED",
    "from": {
      "asset": "EUR",
      "amount": 100
    },
    "to": {
      "asset": "LTC",
      "amount": 1.386770212175842462
    },
    "orders": [
      {
        "symbol": "LTC-EUR",
        "side": "BUY",
        "targetPrice": 72.11,
        "targetQuantity": 1.386770212175842462,
        "venue": "kraken",
        "output": 0,
        "id": "234098b4-f55b-4ef6-9ea3-1d28010d8476",
        "venueOrderId": "cd5009ad-ecd4-438a-813c-7608c85833d7",
        "status": "CANCELLED",
        "actualPrice": 72.050216507121990198,
        "actualQuantity": 0.21356492612732545,
        "createdAt": "2024-05-01T14:49:43.157286Z"
      },
      {
        "symbol": "LTC-EUR",
        "side": "BUY",
        "targetPrice": 72.11,
        "targetQuantity": 1.173382344115915787,
        "venue": "kraken",
        "output": 0,
        "id": "a1c86126-9c56-407a-902c-a89a15d198f1",
        "venueOrderId": "5e893e50-9260-435a-ac5c-e7430dbf34e5",
        "status": "COMPLETED",
        "actualPrice": 72.11,
        "actualQuantity": 1.17338234,
        "createdAt": "2024-05-01T14:50:44.788691Z"
      }
    ],
    "router": "VWAP",
    "executor": "MAKER",
    "movements": [
      {
        "asset": "LTC",
        "amount": 1.38694726612732545
      },
      {
        "asset": "EUR",
        "amount": -99.9999997032013125489753309548559391
      }
    ],
    "createdAt": "2024-05-01T14:49:43.151138Z"
  }
}

Below is a detailed explanation of each field in the webhook payload:

Field	Type	Description
event	string	Identifies the type of event, for example, "layer1:trade:conversion:state-changed".
timestamp	string	ISO 8601 formatted date and time when the event was generated.
data.id	string	Unique identifier for the conversion event, in GUID format.
data.reference	string	A reference identifier linked to the conversion, in GUID format.
data.status	string	Current status of the conversion [PLACED, COMPLETE].
data.from.asset	string	Type of asset being converted from.
data.from.amount	float	Amount of the asset being converted.
data.to.asset	string	Type of asset being converted to.
data.to.amount	float	Amount of the asset received after conversion.
data.orders[]	array	Array containing details of orders involved in the conversion.
data.orders[].symbol	string	Trading pair symbol.
data.orders[].side	string	Transaction side.
data.orders[].targetPrice	float	Target price for the order.
data.orders[].targetQuantity	float	Target quantity for the order.
data.orders[].venue	string	Venue where the order was placed.
data.orders[].output	int	Output index of the order (for complex trades involving multiple orders).
data.orders[].id	string	Unique identifier for the order, in GUID format.
data.orders[].venueOrderId	string	Unique identifier provided by the trading venue for the order, in GUID format.
data.orders[].status	string	Current status of the order [PLACED, COMPLETED].
data.orders[].actualPrice	float	Actual price at which the order was executed.
data.orders[].actualQuantity	float	Actual quantity of the asset received from the order.
data.orders[].createdAt	string	ISO 8601 formatted date and time when the order was created.
data.router	string	Routing mechanism used for the conversion [VWAP].
data.executor	string	Type of execution used for processing the conversion [MAKER].
data.movements[]	array	Array detailing any asset movements and amounts related to the conversion.
data.createdAt	string	ISO 8601 formatted date and time when the conversion was created.

---

layer1:digital:balance:updated

The webhook notification sends a JSON object containing details about the event. Here is the example payloads:

{
  "event": "layer1:digital:balance:updated",
  "timestamp": "2024-06-05T20:40:16.941138099Z",
  "data": {
    "reference": "First Eth Address",
    "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
    "asset": "ETH",
    "funds": [
      {
        "type": "AVAILABLE",
        "balance": "0.00",
        "delta": "0.00"
      },
      {
        "type": "BLOCKCHAIN",
        "balance": "0.20",
        "delta": "0.20"
      },
      {
        "type": "RESERVED",
        "balance": "0.20",
        "delta": "0.20"
      }
    ]
  }
}

Below is a detailed explanation of each field in the webhook payload:

Field	Description
event	The type of event that triggered the webhook.
timestamp	The time when the event occurred in ISO 8601 format.
data	A nested object containing details of the balance update.
data.reference	A unique reference for the crypto address.
data.address	The crypto address involved in the balance update.
data.asset	The type of cryptocurrency asset.
data.funds	An array containing details of the fund balances.
data.funds.type	The type of fund balance [AVAILABLE, BLOCKCHAIN, RESERVED].
data.funds.balance	The current balance of the fund type.
data.funds.delta	The change in balance for the fund type.