Webhook Types

Webhook으로 구독 가능한 이벤트 타입과, 각 타입에 대해 사용 가능한 condition 설정 방법을 확인할 수 있습니다.

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

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

eventTypedescription
ADDRESS_ACTIVITY특정 주소가 from 또는 to에 포함된 트랜잭션에 대한 trace 변경사항 및 트랜잭션 발생을 알림으로 받을 수 있습니다.
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개의 블록 생성시마다 알림을 받도록 설정할 수 있습니다.
NEW_HEADS새로운 블록이 확정되어 Head로 지정될 때마다 알림을 받도록 설정할 수 있습니다.
BLOCK_LIST_CALLER대상 주소와 여러 Blocklist 계정 주소를 등록한 뒤, 해당 Blocklist주소들로부터 대상 주소로 Native Token 또는 ERC20 토큰이 전송되었을 때 알림을 받을 수 있습니다.
ALLOW_LIST_CALLER대상 주소와 여러 Allowlist 계정 주소를 등록한 뒤, 해당 Allowlist주소들로부터 대상 주소로 Native Token 또는 ERC20 토큰이 전송되었을 때 알림을 받을 수 있습니다.
LOG지정한 스마트 컨트랙트에서 특정 Topic에 해당하는 이벤트 LOG가 발생하는 경우 알림을 받을 수 있습니다.

이벤트 별 요청/알림 예제

ADDRESS_ACTIVITY

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

KeyTypeRequiredDescriptionExample Value
addressesArray of Stringtrue이벤트를 모니터링 하고자 하는 주소들의 목록입니다.["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 타입 이벤트 발생시 'trace'와 'transaction', 'erc20', 'erc721', 그리고 'erc1155'의 메세지 타입의 알림을 수신할 수 있습니다.

{
  "subscriptionId": "602",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/addressactivity"
  },
  "eventType": "ADDRESS_ACTIVITY",
  "createdAt": "2023-11-30T09:37:52.691Z",
  "event": {
    "targetAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "message": {
      "block_hash": "0xc3d6be9b093c7baa88e80228ab1101f9b0b1048a79422e5b4eef0ee6b2eaafda",
      "block_number": 18683570,
      "block_timestamp": 1701336971,
      "transaction_index": 26,
      "transaction_hash": "0xb2fa562091fcb87dc3b640f6bbd303c4b373dd492a38585fca4dc83febcba965",
      "from_address": "0xd91efec7e42f80156d1d9f660a69847188950747",
      "to_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "value": "0",
      "input": "0xa9059cbb000000000000000000000000dc824bc300776e5096ef2255377d94977483be61000000000000000000000000000000000000000000000000000000000a5f0780",
      "output": "0x",
      "trace_type": "call",
      "call_type": "call",
      "gas": 829941,
      "gas_used": 41601,
      "subtraces": 0,
      "trace_address": [
        0,
        7
      ],
      "error": null,
      "status": 1,
      "revert_reason": null,
      "trace_id": "call_18683570_26_0_7",
      "reward_type": null,
      "type": "trace",
      "author": null
    }
  }
}

{
  "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 객체 필드는 아래와 같습니다.

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

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

KeyTypeRequiredDescriptionExample Value
addressesArray of Stringtrue트랜잭션 이벤트를 모니터링 하고자 하는 주소들의 목록입니다. 각 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 객체 필드는 아래와 같습니다.

KeyTypeRequiredDescriptionExample Value
tokensArray of objecttrue전송 이벤트를 모니터링 하고자 하는 토큰 정보 객체
tokens[i].contractAddressStringtrue모니터링 하고자 하는 ERC20 또는 ERC721 토큰의 컨트랙트 주소"0xdac17f958d2ee523a2206206994597c13d831ec7"
tokens[i].tokenIdStringfalse해당 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 객체 필드는 아래와 같습니다.

KeyTypeRequiredDescriptionExample Value
addressStringtrue잔고 알림을 받고자 하는 대상 주소"0xc90d3Ac75D1D36dF0b0a229E73D8409FB7F3c4ab"
belowThresholdBalanceStringtrue모니터링 하고자 하는 잔고의 임계값. 해당 임계값 밑으로 잔고가 떨어지는 경우, 알림을 받을 수 있습니다."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, NEW_HEADS

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

KeyTypeRequiredDescriptionExample Value
periodIntegertrue이벤트 알림을 받을 블록 주기 설정의 값. 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
    }
  }
}

{
  "subscriptionId": "574",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "NEW_HEADS",
  "createdAt": "2023-12-05T08:31:26.903Z",
  "event": {
    "message": {
      "parent_hash": "0x7a9719642f7f0919f9abbc9ede7a43db65888a9049001cd3aab457092220a491",
      "sha3_uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "miner": "0x388c818ca8b9251b393131c08a736a67ccb19297",
      "state_root": "0x12049706c8fcfa5d7e61fa4144e496a9094092b6f25f1df79f2a749f59088699",
      "transactions_root": "0x67d94e96fb60d4ff271fdf62bd53530af177c74d47bf6c6526834bf3dedf2ca0",
      "receipts_root": "0x5880960bc8b4ae3030eb2ae29559c71613ccc724b0ccf6a4a7a149c175500b7c",
      "logs_bloom": "0x977512830d91f135121a96548c1274a1d1dc0083e0550004641b084cd4033af2680f03a50210202a42940b20828401f4c22bc0229a20340254d1f09ab56ce4822ed1419f0146cbbfead045fac4f76432058201c91c411803b0cdcb70c86902ecd923693c02ac601da12dd0701c811fce34700c1700e38c0bc53e013e496c6bb80b26b8d1612e00bc2447839d124e08026520a9d1092714bc0c058ce95c79e410528904cf48a47cc416625088cf109db817c48f03112a9a8086e0395095295af649d809d200f4c81c5341990401de90944925890306aa885422cc721a6aac3204045a26c028070d5231a6d645b2a5b48c9580f113257810cda1102025bb15541e",
      "difficulty": "0",
      "gas_limit": 30000000,
      "gas_used": 13230886,
      "extra_data": "0x546974616e2028746974616e6275696c6465722e78797a29",
      "mix_hash": "0x3bcabbccb858d140670cab57fe6606a218706534b92f528737e68ba5ec1f2a03",
      "nonce": "0x0000000000000000",
      "hash": "0xd4b2ee3d71680db870851e43061fba9a919c0b112a360b2d8f0ad24878678d3a",
      "size": 203276,
      "total_difficulty": "58750003716598352816469",
      "transactions": [
        "0x805a8625844a8f96faed6f0661a5c96d374ad3a139f3677ff265b0e96b1d1453",
        "0x935c926f06567aa2147d8a958f33a9626a8ad258c8c1ecdc471786ad07e43a59",
        // ...
      ],
      "transaction_count": 146,
      "log_count": 287,
      "base_fee_per_gas": 44382058743,
      "withdrawals_root": "0x24b0d7c643ec591b899253aadcd192704b835decbe8ee558c54bd38ac1ff1534",
      "withdrawal_count": 16,
      "type": "block",
      "number": 18718961,
      "timestamp": 1701764987
    }
  }
}

BLOCK_LIST_CALLER, ALLOW_LIST_CALLER

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

KeyTypeRequiredDescriptionExample Value
addressStringtrue토큰 전송 이벤트를 모니터링 하고자 하는 대상 주소 0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B
blockListCallersArray of Stringtrue대상 주소로 토큰 전송이 발생하는 경우 알림을 받고자 하는 주소의 목록 ["0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B",
"0xADa221F5498F573583228B5Ad1e987cFF48Bd4cC"]

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

KeyTypeRequiredDescriptionExample Value
addressStringtrue토큰 전송 이벤트를 모니터링 하고자 하는 대상 주소 0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B
allowListCallersArray of Stringtrue대상 주소로 토큰 전송이 발생하는 경우 알림을 받고자 하는 주소의 목록["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"
    }
  }
}

LOG

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

KeyTypeRequiredDescriptionExample Value
addressStringtrue모니터링 대상 컨트랙트의 주소(CA) "0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B"
topicsArray of Stringtrue모니터링 하고자 하는 LOG의 토픽 목록 [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x00000000000000000000000056178a0d5f301baf6cf3e1cd53d9863437345bf9",
"0x00000000000000000000000060594a405d53811d3bc4766596efd80fd545a270

📘

topics에는 어떤 값을 넣어야 하나요?

topics에는 조회하고자 하는 event의 정보를 입력합니다. Ethereum의 스마트 컨트랙트 이벤트는 로그의 형태로 저장되며, 이 로그들은 topics라는 배열을 통해 인덱싱됩니다. topics에는 아래와 같이 최대 네 가지 값을 입력할 수 있습니다.

  1. topics[0]: 이벤트 시그니처 (Event Signature). 이는 이벤트의 이름과 입력 파라미터 타입을 해시한 값입니다. 예를 들어, Transfer(address,address,uint256) 이벤트의 경우, 해당 문자열을 keccak256 해시 함수로 해시한 값이 topics[0]에 들어갑니다.
  2. topics[1] ~ topics[3]: 이벤트의 인덱싱된 파라미터 (Indexed Parameters). 스마트 컨트랙트의 이벤트 정의에서 indexed 키워드로 표시된 파라미터들이 여기에 해당합니다. 이 파라미터들은 이벤트 로그를 필터링하는 데 사용됩니다. 예를 들어, Transfer(address indexed from, address indexed to, uint256 value) 이벤트의 경우, from과 to 주소가 각각 topics[1]과 topics[2]에 해당합니다.
    • topics[1], topics[2], topics[3]은 선택적입니다. 이벤트에 인덱싱된 파라미터가 없다면 이 필드들은 비워둘 수 있습니다.
    • 인덱싱된 파라미터가 여러 개 있는 경우, topics 배열에서 해당 순서대로 나타납니다.
    • 인덱싱된 파라미터 값은 64자리의 16진수로 변환되어야 합니다. 이는 Ethereum의 데이터 표현 방식에 따른 것으로, 각 파라미터 값은 32바이트 길이의 16진수로 인코딩되어 topics 배열에 저장됩니다.

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": "LOG",
    "notification": {
        "webhookUrl": "https://webhook.test.server/log"
    },
    "condition": {
        "address": "0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B",
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x00000000000000000000000056178a0d5f301baf6cf3e1cd53d9863437345bf9",
          "0x00000000000000000000000060594a405d53811d3bc4766596efd80fd545a270",
        ]
    }
}'

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

Webhook 생성 후 대상 스마트 컨트랙트에서 지정한 Event Topic Log가 발생하는 경우, 아래와 같은 Webhook 메시지가 전달됩니다.

{
  "subscriptionId": "583",
  "description": "",
  "protocol": "ETHEREUM",
  "network": "MAINNET",
  "subscriptionType": "WEBHOOK",
  "notification": {
    "webhookUrl":"https://webhook.test.server/"
  },
  "eventType": "LOG",
  "createdAt": "2023-12-05T09:02:51.389Z",
  "event": {
    "targetAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    ],
    "message": {
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x0000000000000000000000008bfcff855c765028964eab55d6585332d7acaf63",
        "0x000000000000000000000000a572e7c86cf62aa737fdb1f2a5ba16f47fb54b51"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000000000036d61600",
      "block_number": 18719118,
      "transaction_hash": "0x46bd432d267b436dd86aadad5373e4722cb56eeafc03a14eec1c17db3769f8e0",
      "transaction_index": 27,
      "block_hash": "0x01635cc4060bd05cf99bed9a2db9574f4f6c8af25b5661c22f3b5a2c090c3541",
      "block_timestamp": 1701766871,
      "log_index": 69,
      "removed": false,
      "type": "log"
    }
  }
}