Webhook Types

Webhook으로 등록 가능한 이벤트 타입(eventType) 목록

루니버스 Web3 Engine에서는 아래 eventType들에 대해 Webhook을 생성할 수 있습니다.

`eventType`	description
ADDRESS_ACTIVITY	특정 주소가 from 또는 to에 포함된 트랜잭션에 대한 트랜잭션 발생을 알림으로 받을 수 있습니다.
TRANSACTION	트랜잭션을 실행하고 반환받은 hash를 이용하여 해당 트랜잭션이 포함된 블록이 마이닝되면 알림으로 받을 수 있습니다.
MINED_TRANSACTION	특정 주소가 from에 포함된 트랜잭션이 최종 채굴 완료되었을 때 트랜잭션 receipt 정보를 알림으로 받을 수 있습니다.
SUCCESSFUL_TRANSACTION	특정 주소가 from에 포함된 트랜잭션의 상태가 성공적으로 처리되었을 때(receipt상 상태 코드가 0x1인 경우)알림을 받을 수 있습니다.
FAILED_TRANSACTION	특정 주소가 from에 포함된 트랜잭션이 정상적으로 처리되지 못한 경우(receipt상 상태 코드가 0x0인 경우)알림을 받을 수 있습니다.
TOKEN_TRANSFER	특정 ERC20, ERC721, 또는 ERC1155 토큰의 Transfer 이벤트가 발생한 경우 알림을 받을 수 있습니다. 컨트랙트 주소를 지정할 수 있으며, ERC721과 ERC1155는 특정 토큰 ID로 조건을 설정할 수 있습니다.
BELOW_THRESHOLD_BALANCE	지정한 계정의 잔고가 설정한 수치 이하로 떨어지면 알림을 받을 수 있습니다.
BLOCK_PERIOD	네트워크 블록 생성 주기에 따라 알림을 받을 수 있습니다. 주기 값에 따라 매 블록 또는 N개의 블록 생성시마다 알림을 받도록 설정할 수 있습니다.
BLOCK_LIST_CALLER	대상 주소와 여러 Blocklist 계정 주소를 등록한 뒤, 해당 Blocklist주소들로부터 대상 주소로 Native Token 또는 ERC20 토큰이 전송되었을 때 알림을 받을 수 있습니다.
ALLOW_LIST_CALLER	대상 주소와 여러 Allowlist 계정 주소를 등록한 뒤, 해당 Allowlist주소들로부터 대상 주소로 Native Token 또는 ERC20 토큰이 전송되었을 때 알림을 받을 수 있습니다.

이벤트 별 요청/알림 예제

ADDRESS_ACTIVITY

eventType값을 ADDRESS_ACTIVITY로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다. Value에 등록된 모든 주소들과 관련된 트랜잭션이 발생하는 경우 Webhook에 등록된 notification 채널로 알림이 전송됩니다.

Key	Type	Required	Description	Example Value
addresses	Array of String	true	이벤트를 모니터링 하고자 하는 주소들의 목록입니다.	["0xc90d3Ac75D1D36dF0b0a229E73D8409FB7F3c4ab", "0x56Eddb7aa87536c09CCc2793473599fD21A8b17F"]

ADDRESS_ACTIVITY 호출 예제

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST_DESCRIPTION",
    "eventType": "ADDRESS_ACTIVITY",
    "notification": {
        "webhookUrl": "https://webhook.test.server/addressactivity"
    },
    "condition": {
        "addresses":["0x56eddb7aa87536c09ccc2793473599fd21a8b17f"]
    }
}'

이벤트 발생시 Webhook Url로 호출되는 requestBody 예제

ADDRESS_ACTIVITY 타입 이벤트 발생시 'transaction'와 'erc20', 'erc721', 그리고 'erc1155'의 메세지 타입의 알림을 수신할 수 있습니다.

{
  "subscriptionId": "561",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/addressactivity"
  },
  "eventType": "ADDRESS_ACTIVITY",
  "createdAt": "2023-12-05T07:48:14.322Z",
  "event": {
    "targetAddress": "0x457dc75cb06ed7a58bf2dde3e9121f8df440e0a9",
    "message": {
      "block_hash": "0x0136bfe3ba7736bc03efd29358dd1dfafbe4acf5b069002c0d7dfb3315ddf8c7",
      "block_number": 18718746,
      "block_timestamp": 1701762395,
      "from_address": "0x457dc75cb06ed7a58bf2dde3e9121f8df440e0a9",
      "gas": 94813,
      "gas_price": 46842415159,
      "hash": "0x2b0ee8dafb56f15f0ad5792fc97cff3f5d0922a0fe144e5c1a8d11f3e5689399",
      "input": "0xa9059cbb000000000000000000000000356e721a3696833db6faa9f86b1dd118e2d67d150000000000000000000000000000000000000000000000000000000034553780",
      "max_fee_per_gas": 59943044505,
      "max_priority_fee_per_gas": 31966350,
      "nonce": 0,
      "to_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "transaction_index": 113,
      "transaction_type": 2,
      "value": "0",
      "access_list": [],
      "receipt_contract_address": null,
      "receipt_cumulative_gas_used": 13751307,
      "receipt_effective_gas_price": 46842415159,
      "receipt_gas_used": 63209,
      "receipt_root": null,
      "receipt_status": 1,
      "type": "transaction"
    }
  }
}

{
  "subscriptionId": "602",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/addressactivity"
  },
  "eventType": "ADDRESS_ACTIVITY",
  "createdAt": "2023-11-30T09:37:53.676Z",
  "event": {
    "targetAddress": "0xb517850510997a34b4ddc8c3797b4f83fad510c4",
    "message": {
      "token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "from_address": "0xb517850510997a34b4ddc8c3797b4f83fad510c4",
      "to_address": "0xa3a0f67a1eb55988c3e3f1c36e4133d39a6312b3",
      "value": "50000000000000000",
      "transaction_hash": "0xb4e3c67948c0d04759bcf80d8fc83655550f905e3caa92e03f1893e7e5efb46e",
      "log_index": 273,
      "block_number": 18683570,
      "block_timestamp": 1701336971,
      "type": "erc20"
    }
  }
}

{
  "subscriptionId": "561",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/addressactivity"
  },
  "eventType": "ADDRESS_ACTIVITY",
  "createdAt": "2023-12-05T07:40:51.349Z",
  "event": {
    "targetAddress": "0x4118f1e74d693dace7cb22f5482089be79164fe2",
    "message": {
      "token_address": "0x524cab2ec69124574082676e6f654a18df49a048",
      "from_address": "0x4118f1e74d693dace7cb22f5482089be79164fe2",
      "to_address": "0xe2f7dc39f08969a6c248b878c53ae042a9ff4cb4",
      "token_id": "15503",
      "transaction_hash": "0x88c64047dff230c4a575852de489479a0381f83cc1aa317cc93dcb70ab3c671c",
      "log_index": 238,
      "block_number": 18718709,
      "block_timestamp": 1701761951,
      "type": "erc721"
    }
  }
}

{
  "subscriptionId": "561",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/addressactivity"
  },
  "eventType": "ADDRESS_ACTIVITY",
  "createdAt": "2023-12-05T07:40:38.921Z",
  "event": {
    "targetAddress": "0x07bf13b3fcfd66414b63b51d5a422cf1ec85f765",
    "message": {
      "token_address": "0xb9e69221fa305d6de9f8d907ee7d9bb10697023e",
      "from_address": "0x07bf13b3fcfd66414b63b51d5a422cf1ec85f765",
      "to_address": "0xa2ab3abfa88d9d26103ff2451d07244e1df3442c",
      "value": "1",
      "token_id": "2",
      "operator": "0x1e0049783f008a0085193e00003d00cd54003c71",
      "transaction_hash": "0xa44dadbc10b409218913de8db681b9ebbb7f9a07549bbb70d10a0134644f1e4a",
      "log_index": 224,
      "batch_index": 0,
      "block_number": 18718708,
      "block_timestamp": 1701761939,
      "type": "erc1155"
    }
  }
}

TRANSACTION, MINED_TRANSACTION, SUCCESSFUL_TRANSACTION, FAILED_TRANSACTION

eventType값을 TRANSACTION으로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
txHash	String	true	트랜잭션을 실행하고 반환받은 Hash를 이용하 해당 트랜잭션이 포함된 블록이 마이닝되면 알림을 수신할 수 있습니다.	"0x13df215746d8f5046028f1d0cdd7539d891d3956f86de65e211c0a9a01b0f345"

eventType값을 MINED_TRANSACTION, SUCCESSFUL_TRANSACTION, FAILED_TRANSACTION 타입으로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
addresses	Array of String	true	트랜잭션 이벤트를 모니터링 하고자 하는 주소들의 목록입니다. 각 address가 From 또는 to에 포함된 트랜잭션이 발생하는 경우 알림을 수신할 수 있습니다.	["0x90d3Ac75D1D36dF0b0a229E73D8409FB7F3c4ab", "0x56Eddb7aa87536c09CCc2793473599fD21A8b17F"]

createWebhook API 호출 예제

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST_DESCRIPTION",
    "eventType": "MINED_TRANSACTION",
    "notification": {
        "webhookUrl": "https://webhook.test.server/minedtransaction"
    },
    "condition": {
        "addresses":["0x56eddb7aa87536c09ccc2793473599fd21a8b17f"]
    }
}'

이벤트 발생시 Webhook Url로 호출되는 requestBody 예제

TRANSACTION 타입 이벤트 발생시 transaction receipt를 알림의 event.message 필드로 수신할 수 있습니다. 각 eventType에 정의된 조건에 맞는 트랜잭션들만 필터링 되어 전달됩니다.

{
  "subscriptionId": "567",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "TRANSACTION",
  "createdAt": "2023-12-05T08:15:27.006Z",
  "event": {
    "message": {
      "block_hash": "0xde216647da147052cc91c352485a50d444c6bc445acf7dd7fe6defefa41aa179",
      "block_number": 18718882,
      "block_timestamp": 1701764027,
      "from_address": "0x9e12524c0ef025dea0a7505e33d8bb3f8d0001d1",
      "gas": 44206,
      "gas_price": 45187037499,
      "hash": "0x909882c3196f810f1faf2a0a950195b79f35d896d5399563f118fa31b13b3674",
      "input": "0xf14fcbc8179db114435e7f04a90f9f2690ee370d8fe1c886ee5020c0db9e16bb44f53ac7",
      "max_fee_per_gas": 58334943304,
      "max_priority_fee_per_gas": 100000000,
      "nonce": 0,
      "to_address": "0x253553366da8546fc250f225fe3d25d0c782303b",
      "transaction_index": 62,
      "transaction_type": 2,
      "value": "0",
      "access_list": [],
      "receipt_contract_address": null,
      "receipt_cumulative_gas_used": 5157953,
      "receipt_effective_gas_price": 45187037499,
      "receipt_gas_used": 44206,
      "receipt_root": null,
      "receipt_status": 1,
      "type": "transaction"
    }
  }
}

{
  "subscriptionId": "562",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "MINED_TRANSACTION",
  "createdAt": "2023-12-05T07:54:13.870Z",
  "event": {
    "targetAddress": "0x7b659f64a1e476e35c7d408384c122787fed4bd7",
    "message": {
      "block_hash": "0x74fac3768fc78346a70d7b2daac91eeedbedee210ae0455013c157c79dd2d952",
      "block_number": 18718776,
      "block_timestamp": 1701762755,
      "from_address": "0x7b659f64a1e476e35c7d408384c122787fed4bd7",
      "gas": 21000,
      "gas_price": 41536698318,
      "hash": "0x8962d7583c24696e9aa4ccf3883a3642844e0005794202ec03ff91aacd092909",
      "input": "0x",
      "max_fee_per_gas": 60451650622,
      "max_priority_fee_per_gas": 100000000,
      "nonce": 373,
      "to_address": "0xaf1b439cffa2ede043f69cc4d18aa81675e13f5e",
      "transaction_index": 130,
      "transaction_type": 2,
      "value": "4000000000000000",
      "access_list": [],
      "receipt_contract_address": null,
      "receipt_cumulative_gas_used": 17235147,
      "receipt_effective_gas_price": 41536698318,
      "receipt_gas_used": 21000,
      "receipt_root": null,
      "receipt_status": 1,
      "type": "transaction"
    }
  }
}

{
  "subscriptionId": "564",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "SUCCESSFUL_TRANSACTION",
  "createdAt": "2023-12-05T07:58:48.914Z",
  "event": {
    "targetAddress": "0x8c3290ed5c6713218f27ec58f457f4130f0dfe54",
    "message": {
      "block_hash": "0x90437ed30b39b9804bbd363f007bfaa904ebbbccf82dcf356256f2f914574072",
      "block_number": 18718799,
      "block_timestamp": 1701763031,
      "from_address": "0x8c3290ed5c6713218f27ec58f457f4130f0dfe54",
      "gas": 21000,
      "gas_price": 44786253275,
      "hash": "0x976d0de0ab9a6e1606bd7904df7e968bdf702d15ac992ed754f803e2c1cec00c",
      "input": "0x",
      "max_fee_per_gas": 54173627349,
      "max_priority_fee_per_gas": 31966350,
      "nonce": 424,
      "to_address": "0x3714fa4dabf6a58dc32015d63f792a448aa41c5a",
      "transaction_index": 192,
      "transaction_type": 2,
      "value": "2527019000000000000",
      "access_list": [],
      "receipt_contract_address": null,
      "receipt_cumulative_gas_used": 15067379,
      "receipt_effective_gas_price": 44786253275,
      "receipt_gas_used": 21000,
      "receipt_root": null,
      "receipt_status": 1,
      "type": "transaction"
    }
  }
}

{
  "subscriptionId": "566",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "FAILED_TRANSACTION",
  "createdAt": "2023-12-05T08:12:14.526Z",
  "event": {
    "targetAddress": "0x1185881673ebd0cc86cf36e9d15ca0fd6c3b29ae",
    "message": {
      "block_hash": "0xe6cfae05462866f0f05c32a93e561b902f4ce9b1fd7585fc97da3a60c211ead4",
      "block_number": 18718866,
      "block_timestamp": 1701763835,
      "from_address": "0x1185881673ebd0cc86cf36e9d15ca0fd6c3b29ae",
      "gas": 240009,
      "gas_price": 43016551632,
      "hash": "0x1dba157ce040bb93a02ec225a974fb882585ae18e393c39a8bb7d92913101851",
      "input": "0xd9627aa4000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000003782dace9d900000000000000000000000000000000000000000000000000000001dcc47ab2d9aa00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000c7b199ac2bca0dba8d1785480648f0318b9a7b8869584cd0000000000000000000000001000000000000000000000000000000000000011000000000000000000000000000000009a463a0cd7b6f8a150450e97621f47ea",
      "max_fee_per_gas": 49000000000,
      "max_priority_fee_per_gas": 50000000,
      "nonce": 631,
      "to_address": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
      "transaction_index": 130,
      "transaction_type": 2,
      "value": "250000000000000000",
      "access_list": [],
      "receipt_contract_address": null,
      "receipt_cumulative_gas_used": 8552466,
      "receipt_effective_gas_price": 43016551632,
      "receipt_gas_used": 160006,
      "receipt_root": null,
      "receipt_status": 0,
      "type": "transaction"
    }
  }
}

TOKEN_TRANSFER

eventType값을 TOKEN_TRANSFER 로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
tokens	Array of object	true	전송 이벤트를 모니터링 하고자 하는 토큰 정보 객체
tokens[i].contractAddress	String	true	모니터링 하고자 하는 ERC20 또는 ERC721 토큰의 컨트랙트 주소	"0xdac17f958d2ee523a2206206994597c13d831ec7"
tokens[i].tokenId	String	false	해당 ERC721 컨트랙트의 특정 토큰에 대한 전송 이벤트만 모니터링 하고자 하는 경우 토큰 ID를 지정하기 위한 필드	"153"

🚧
contractAddress 입력시 주의 사항
대량의 Transfer가 발생하는 Token 컨트랙트를 입력한 경우, Webhook 응답의 딜레이가 발생할 수 있습니다.

createWebhook API 호출 예제

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST_DESCRIPTION",
    "eventType": "TOKEN_TRANSFER",
    "notification": {
        "webhookUrl": "https://webhook.test.server/tokentransfer"
    },
    "condition": {
        "tokens":[
            {
                "contractAddress":"0xdac17f958d2ee523a2206206994597c13d831ec7"
            }
        ]
    }
}'

이벤트 발생시 Webhook Url로 호출되는 requestBody 예제

TOKEN_TRANSFER 타입의 Webhook 생성 후 지정한 토큰 컨트랙트 또는 특정 토큰의 전송 이벤트가 발생하는 경우 아래와 같은 전송 이벤트 정보가 Webhook URL로 전달됩니다. ERC-20 이벤트의 경우 event.message.value가 전송 수량을 의미하며, ERC-721 이벤트의 경우 event.message.value가 전송된 토큰의 ID를 의미합니다.

{
  "subscriptionId": "602",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "TOKEN_TRANSFER",
  "createdAt": "2023-11-30T09:37:53.676Z",
  "event": {
    "targetAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "message": {
      "token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "from_address": "0xb517850510997a34b4ddc8c3797b4f83fad510c4",
      "to_address": "0xa3a0f67a1eb55988c3e3f1c36e4133d39a6312b3",
      "value": "50000000000000000",
      "transaction_hash": "0xb4e3c67948c0d04759bcf80d8fc83655550f905e3caa92e03f1893e7e5efb46e",
      "log_index": 273,
      "block_number": 18683570,
      "block_timestamp": 1701336971,
      "type": "erc20"
    }
  }
}

{
  "subscriptionId": "561",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "TOKEN_TRANSFER",
  "createdAt": "2023-12-05T07:40:51.349Z",
  "event": {
    "targetAddress": "0x524cab2ec69124574082676e6f654a18df49a048",
    "message": {
      "token_address": "0x524cab2ec69124574082676e6f654a18df49a048",
      "from_address": "0x4118f1e74d693dace7cb22f5482089be79164fe2",
      "to_address": "0xe2f7dc39f08969a6c248b878c53ae042a9ff4cb4",
      "token_id": "15503",
      "transaction_hash": "0x88c64047dff230c4a575852de489479a0381f83cc1aa317cc93dcb70ab3c671c",
      "log_index": 238,
      "block_number": 18718709,
      "block_timestamp": 1701761951,
      "type": "erc721"
    }
  }
}

{
  "subscriptionId": "561",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "TOKEN_TRANSFER",
  "createdAt": "2023-12-05T07:40:38.921Z",
  "event": {
    "targetAddress": "0xb9e69221fa305d6de9f8d907ee7d9bb10697023e",
    "message": {
      "token_address": "0xb9e69221fa305d6de9f8d907ee7d9bb10697023e",
      "from_address": "0x07bf13b3fcfd66414b63b51d5a422cf1ec85f765",
      "to_address": "0xa2ab3abfa88d9d26103ff2451d07244e1df3442c",
      "value": "1",
      "token_id": "2",
      "operator": "0x1e0049783f008a0085193e00003d00cd54003c71",
      "transaction_hash": "0xa44dadbc10b409218913de8db681b9ebbb7f9a07549bbb70d10a0134644f1e4a",
      "log_index": 224,
      "batch_index": 0,
      "block_number": 18718708,
      "block_timestamp": 1701761939,
      "type": "erc1155"
    }
  }
}

BELOW_THRESHOLD_BALANCE

eventType값을 BELOW_THRESHOLD_BALANCE 로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
address	String	true	잔고 알림을 받고자 하는 대상 주소	"0xc90d3Ac75D1D36dF0b0a229E73D8409FB7F3c4ab"
belowThresholdBalance	String	true	모니터링 하고자 하는 잔고의 임계값. 해당 임계값 밑으로 잔고가 떨어지는 경우, 알림을 받을 수 있습니다.	"1000000000000000000000"

📘
알림의 주기는 어떻게 되나요?
1분 마다 해당 주소의 잔고를 조회하며 입력한 THRESHOLD 보다 잔고가 낮을 경우, 알림을 전송합니다. 만약 조회 시점마다 실제 잔고가 belowThresholdBalance에 입력한 값보다 낮은 경우, 알림을 계속해서 받을 수 있습니다.

createWebhook API 호출 예제

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST_DESCRIPTION",
    "eventType": "BELOW_THRESHOLD_BALANCE",
    "notification": {
        "webhookUrl": "https://webhook.test.server/balance"
    },
    "condition": {
        "address": "0xBA826fEc90CEFdf6706858E5FbaFcb27A290Fbe0",		
        "belowThresholdBalance": "3932198180400855840"
    }
}'

이벤트 발생시 Webhook Url로 호출되는 requestBody 예제

BELOW_THRESHOLD_BALANCE 타입의 해당 계정의 잔고가 설정한 Threshold 이하로 내려가면, 아래와 같은 정보가 Webhook URL로 전달됩니다.

{
  "subscriptionId": "569",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "BELOW_THRESHOLD_BALANCE",
  "createdAt": "2023-12-05T08:27:53.630Z",
  "event": {
    "message": {
      "type": "belowThresholdBalance",
      "address": "0x41FBf6b0Da25cDe27f63E1346E5D9787403c8D41",
      "threshold": "76120068240048420",
      "balance": "75120068240048420"
    }
  }
}

BLOCK_PERIOD

eventType값을 BLOCK_PERIOD 로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
period	Integer	true	이벤트 알림을 받을 블록 주기 설정의 값. 1로 설정하는 경우 매 블록이 생성될 때마다 알림을 받을 수 있습니다.	3

createWebhook API 호출 예제

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST_DESCRIPTION",
    "eventType": "BLOCK_PERIOD",
    "notification": {
        "webhookUrl": "https://webhook.test.server/block"
    },
    "condition": {
        "period":3
    }
}'

이벤트 발생시 Webhook Url로 호출되는 requestBody 예제

Webhook 생성 후 설정한 주기만큼의 블록이 Confirm 또는 전파되면, 아래와 같은 Webhook 메시지가 전달됩니다.

{
  "subscriptionId": "573",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "BLOCK_PERIOD",
  "createdAt": "2023-12-05T08:29:38.727Z",
  "event": {
    "period": 1,
    "message": {
      "parent_hash": "0x12da4d638fbf890e47a31abf9d511d53182d5cfa45337ea2d08c776590d42eda",
      "sha3_uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "miner": "0x6c52b959b07e57b4a80c9266a3e24e2b681c410b",
      "state_root": "0x31216db170a54f65486c29b5a674e9aa32252329cdb7501b35ccc64c108b2b8e",
      "transactions_root": "0xa0ca477b3af75ccaacf571d89fff073822d47eb8485c04f6cdceec8ced623ab7",
      "receipts_root": "0xe1829d3c12d4cddaf3882fa90dc5729c3604bca193db8b8a9f3a9a14e83aa0d8",
      "logs_bloom": "0x34a359611084600c80044101800040b251002208428304c2908d80016822e4324c182c80041181444840952824428900134d22009b8820911845812c902c14408b84908b4a2a98ad2925c3ae1421206088a5129941c44813205048b0a860c2c1826a6160836729a8080c4160d0025c64652c0201442b85510e060572080800a61468887c8022039c8048622b0330a0462218330d85d4444826121ac0b410560093472522304070c33211d3ac4d231ec005c00cb8624848982410b11e6248143610140422b014080000408c4222801043edcca5001304e87c0e04108abb80f240105e246a6804c48ea46c41a010228102c488b5088126b24e0060a0842201c4a8",
      "difficulty": "0",
      "gas_limit": 30000000,
      "gas_used": 12056216,
      "extra_data": "0xd883010d05846765746888676f312e32312e34856c696e7578",
      "mix_hash": "0x5bfae80bf4e940e4c7190f15e3dc032b5a263eff597bb2fd45cc6fda10e43df4",
      "nonce": "0x0000000000000000",
      "hash": "0xb9d28da8fa417b22d562a38fd394e452fe21c05c60d317fa75b82434d5d078b3",
      "size": 322154,
      "total_difficulty": "58750003716598352816469",
      "transactions": [
        "0x27a3d95ab2545df627e77c3a36149c91f13b9e5e58339373d298a195b4ebfa34",
        "0x56e747c4c50e4484639c68eb4de1681518bfa7edab90ad41037379e658a22545",
        // ...
      ],
      "transaction_count": 117,
      "log_count": 187,
      "base_fee_per_gas": 48281763437,
      "withdrawals_root": "0xbdd1524cabb3852efdadbd82a03f80b815f7b0f441422767aa5a1722f05e286a",
      "withdrawal_count": 16,
      "type": "block",
      "number": 18718952,
      "timestamp": 1701764867
    }
  }
}

BLOCK_LIST_CALLER, ALLOW_LIST_CALLER

eventType값을 BLOCK_LIST_CALLER 로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
address	String	true	토큰 전송 이벤트를 모니터링 하고자 하는 대상 주소	0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B
blockListCallers	Array of String	true	대상 주소로 토큰 전송이 발생하는 경우 알림을 받고자 하는 주소의 목록	["0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B", "0xADa221F5498F573583228B5Ad1e987cFF48Bd4cC"]

eventType값을 ALLOW_LIST_CALLER 로 설정하는 경우, 사용 가능한 condition 객체 필드는 아래와 같습니다.

Key	Type	Required	Description	Example Value
address	String	true	토큰 전송 이벤트를 모니터링 하고자 하는 대상 주소	0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B
allowListCallers	Array of String	true	대상 주소로 토큰 전송이 발생하는 경우 알림을 받고자 하는 주소의 목록	["0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B", "0xADa221F5498F573583228B5Ad1e987cFF48Bd4cC"]

createWebhook API 호출 예제

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST_DESCRIPTION",
    "eventType": "BLOCK_LIST_CALLER",
    "notification": {
        "webhookUrl": "https://webhook.test.server/blocklist"
    },
    "condition": {
        "address": "0x5e4e65926ba27467555eb562121fac00d24e9dd2",
        "blockListCallers": [
          "0x6887246668a3b87f54deb3b94ba47a6f63f32985",
          "0xADa221F5498F573583228B5Ad1e987cFF48Bd4cC"
        ]
    }
}'

이벤트 발생시 Webhook Url로 호출되는 requestBody 예제

Webhook 생성 후 등록한 AllowlistCaller 또는 BlocklistCaller로부터 대상 주소로 토큰 전송이 발생하면, 아래와 같은 Webhook 메시지가 전달됩니다.

{
  "subscriptionId": "577",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "BLOCK_LIST_CALLER",
  "createdAt": "2023-12-05T08:56:50.685Z",
  "event": {
    "targetAddress": "0x4e5b2e1dc63f6b91cb6cd759936495434c7e972f",
    "blockListCaller": "0x16add96cb700de9a1575d6d5ee140f730c03facd",
    "message": {
      "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "from_address": "0x16add96cb700de9a1575d6d5ee140f730c03facd",
      "to_address": "0x4e5b2e1dc63f6b91cb6cd759936495434c7e972f",
      "value": "600000000",
      "transaction_hash": "0x0b1037f9cf7d82a402cfc3dc4c7f48f6cb39f3ee33f03a6374f20fe72d1bd260",
      "log_index": 251,
      "block_number": 18719088,
      "block_timestamp": 1701766511,
      "type": "erc20"
    }
  }
}

{
  "subscriptionId": "578",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "ALLOW_LIST_CALLER",
  "createdAt": "2023-12-05T08:56:50.685Z",
  "event": {
    "targetAddress": "0x2336b8f1a7bd8ca346bb2eac74005339b2c0110b",
    "allowListCaller": "0x75e89d5979e4f6fba9f97c104c2f0afb3f1dcb88",
    "message": {
      "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "from_address": "0x75e89d5979e4f6fba9f97c104c2f0afb3f1dcb88",
      "to_address": "0x2336b8f1a7bd8ca346bb2eac74005339b2c0110b",
      "value": "58048582",
      "transaction_hash": "0x45e7a50702cc00240edac614e37d1c9d0fcb9c1221a5a2c6c8c8408005529d58",
      "log_index": 247,
      "block_number": 18719088,
      "block_timestamp": 1701766511,
      "type": "erc20"
    }
  }
}

Webhook Types

Webhook으로 등록 가능한 이벤트 타입(eventType) 목록

이벤트 별 요청/알림 예제

ADDRESS_ACTIVITY

TRANSACTION, MINED_TRANSACTION, SUCCESSFUL_TRANSACTION, FAILED_TRANSACTION

TOKEN_TRANSFER

🚧
contractAddress 입력시 주의 사항

BELOW_THRESHOLD_BALANCE

📘
알림의 주기는 어떻게 되나요?

BLOCK_PERIOD

BLOCK_LIST_CALLER, ALLOW_LIST_CALLER

Webhook으로 등록 가능한 이벤트 타입(eventType) 목록

이벤트 별 요청/알림 예제

ADDRESS_ACTIVITY

TRANSACTION, MINED_TRANSACTION, SUCCESSFUL_TRANSACTION, FAILED_TRANSACTION

TOKEN_TRANSFER

🚧contractAddress 입력시 주의 사항

BELOW_THRESHOLD_BALANCE

📘알림의 주기는 어떻게 되나요?

BLOCK_PERIOD

BLOCK_LIST_CALLER, ALLOW_LIST_CALLER

🚧
contractAddress 입력시 주의 사항

📘
알림의 주기는 어떻게 되나요?