Webhook Types

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

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

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

`eventType`	description
ADDRESS_ACTIVITY	특정 주소가 from 또는 to에 포함된 트랜잭션에 대한 trace 변경사항 및 트랜잭션 발생을 알림으로 받을 수 있습니다.
MINED_TRANSACTION	특정 주소가 from 또는 to에 포함된 트랜잭션이 최종 채굴 완료되었을 때 트랜잭션 receipt 정보를 알림으로 받을 수 있습니다.
SUCCESSFUL_TRANSACTION	특정 주소가 from 또는 to에 포함된 트랜잭션의 상태가 성공적으로 처리되었을 때(receipt상 상태 코드가 0x1인 경우)알림을 받을 수 있습니다.
FAILED_TRANSACTION	특정 주소가 from 또는 to에 포함된 트랜잭션이 정상적으로 처리되지 못한 경우(receipt상 상태 코드가 0x0인 경우)알림을 받을 수 있습니다.
TOKEN_TRANSFER	특정 ERC20 또는 ERC721 토큰의 Transfer 이벤트가 발생한 경우 알림을 받을 수 있습니다. 컨트랙트 주소를 지정할 수 있으며, ERC721 특정 토큰 ID로 조건을 설정할 수 있습니다.
BELOW_THRESHOLD_BALANCE	지정한 계정의 잔고가 설정한 수치 이하로 떨어지면 알림을 받을 수 있습니다.
BLOCK_PERIOD	네트워크 블록 생성 주기에 따라 알림을 받을 수 있습니다. 주기 값에 따라 매 블록 또는 N개의 블록 생성시마다 알림을 받도록 설정할 수 있습니다.
NEW_HEADS	새로운 블록이 Head로 지정될 때마다 알림을 받습니다. BLOCK_PERIOD를 사용하는 경우 Confirmation이 완료된 블록에 대한 이벤트를 받을 수 있는 반면, NEW_HEADS를 사용하는 경우 해당 Head에 대한 Confirmation 상태를 보장하지 않기 때문에 여전히 체인의 재구성 가능성이 있다는 점이 다릅니다.
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 채널로 알림이 전송됩니다.

Key	Type	Required	Description	Example Value
addresses	Array of String	true	이벤트를 모니터링 하고자 하는 주소들의 목록입니다.	["0xc90d3Ac75D1D36dF0b0a229E73D8409FB7F3c4ab", "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": "ADDRESS_ACTIVITY",
    "notification": {
        "webhookUrl": "https://webhook.test.server/addressactivity"
    },
    "condition": {
        "addresses":["0x56eddb7aa87536c09ccc2793473599fd21a8b17f"]
    }
}'

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

ADDRESS_ACTIVITY 타입 이벤트 발생시 'trace'와 'transaction'의 두가지 메세지 타입의 알림을 수신할 수 있습니다.

{
   "subscriptionId":"34",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/addressactivity"
   },
   "eventType":"ADDRESS_ACTIVITY",
   "createdAt":"2023-04-21T10:52:53.040Z",
   "event":{
      "targetAddress":"0x56eddb7aa87536c09ccc2793473599fd21a8b17f",
      "message":{
         "type":"trace",
         "transaction_index":49,
         "from_address":"0x56eddb7aa87536c09ccc2793473599fd21a8b17f",
         "to_address":"0x97169839c817dd38382b497d1552a7e61b33d995",
         "value":19037840000000000,
         "input":"0x",
         "output":"0x",
         "trace_type":"call",
         "call_type":"call",
         "reward_type":null,
         "gas":186128,
         "gas_used":0,
         "subtraces":0,
         "trace_address":[
            0
         ],
         "error":null,
         "status":1,
         "transaction_hash":"0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef",
         "block_number":17094288,
         "trace_id":"call_0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef_",
         "trace_index":156,
         "block_timestamp":1682074271,
         "block_hash":"0x5dac10380f08d9311cd55f3f7b31c36a6e17088f89e42d4a4e9e8d841335125f",
         "item_id":"trace_call_0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef_",
         "item_timestamp":"2023-04-21T10:51:11Z"
      }
   }
}

{
   "subscriptionId":"34",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/addressactivity"
   },
   "eventType":"ADDRESS_ACTIVITY",
   "createdAt":"2023-04-21T10:52:52.738Z",
   "event":{
      "targetAddress":"0x56eddb7aa87536c09ccc2793473599fd21a8b17f",
      "message":{
         "type":"transaction",
         "hash":"0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef",
         "nonce":4702768,
         "transaction_index":49,
         "from_address":"0x56eddb7aa87536c09ccc2793473599fd21a8b17f",
         "to_address":"0x97169839c817dd38382b497d1552a7e61b33d995",
         "value":19037840000000000,
         "gas":207128,
         "gas_price":46391309366,
         "input":"0x",
         "block_timestamp":1682074271,
         "block_number":17094288,
         "block_hash":"0x5dac10380f08d9311cd55f3f7b31c36a6e17088f89e42d4a4e9e8d841335125f",
         "max_fee_per_gas":102000000000,
         "max_priority_fee_per_gas":2000000000,
         "transaction_type":2,
         "receipt_cumulative_gas_used":2933504,
         "receipt_gas_used":21000,
         "receipt_contract_address":null,
         "receipt_root":null,
         "receipt_status":1,
         "receipt_effective_gas_price":46391309366,
         "item_id":"transaction_0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef",
         "item_timestamp":"2023-04-21T10:51:11Z"
      }
   }
}

MINED_TRANSACTION, SUCCESSFUL_TRANSACTION, FAILED_TRANSACTION

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

Key	Type	Required	Description	Example Value
addresses	Array of String	true	트랜잭션 이벤트를 모니터링 하고자 하는 주소들의 목록입니다. 각 address가 from 또는 to에 포함된 트랜잭션이 발생하는 경우 알림을 수신할 수 있습니다.	["0xc90d3Ac75D1D36dF0b0a229E73D8409FB7F3c4ab", "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":"34",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/minedtransaction"
   },
   "eventType":"MINED_TRANSACTION",
   "createdAt":"2023-04-21T10:52:52.738Z",
   "event":{
      "targetAddress":"0x56eddb7aa87536c09ccc2793473599fd21a8b17f",
      "message":{
         "type":"transaction",
         "hash":"0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef",
         "nonce":4702768,
         "transaction_index":49,
         "from_address":"0x56eddb7aa87536c09ccc2793473599fd21a8b17f",
         "to_address":"0x97169839c817dd38382b497d1552a7e61b33d995",
         "value":19037840000000000,
         "gas":207128,
         "gas_price":46391309366,
         "input":"0x",
         "block_timestamp":1682074271,
         "block_number":17094288,
         "block_hash":"0x5dac10380f08d9311cd55f3f7b31c36a6e17088f89e42d4a4e9e8d841335125f",
         "max_fee_per_gas":102000000000,
         "max_priority_fee_per_gas":2000000000,
         "transaction_type":2,
         "receipt_cumulative_gas_used":2933504,
         "receipt_gas_used":21000,
         "receipt_contract_address":null,
         "receipt_root":null,
         "receipt_status":1,
         "receipt_effective_gas_price":46391309366,
         "item_id":"transaction_0xd17f79589038d6435b480045723cc039c955609af82254b3e09ba8f7529473ef",
         "item_timestamp":"2023-04-21T10:51:11Z"
      }
   }
}

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"

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":"38",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/tokentransfer"
   },
   "eventType":"TOKEN_TRANSFER",
   "createdAt":"2023-04-21T11:45:40.636Z",
   "event":{
      "targetAddress":"0xdac17f958d2ee523a2206206994597c13d831ec7",
      "message":{
         "type":"token_transfer",
         "token_address":"0xdac17f958d2ee523a2206206994597c13d831ec7",
         "from_address":"0x74de5d4fcbf63e00296fd95d33236b9794016631",
         "to_address":"0xdf5dccc737705614a87f179ec5b24b40988d5ec9",
         "value":1997957346,
         "transaction_hash":"0x162d1978aa9b321676eae6c4df2b3fe44971431ea5a4e4a639ea43e5280b2091",
         "log_index":150,
         "block_number":17094545,
         "block_timestamp":1682077439,
         "block_hash":"0xc1bbc0a26fbad022fe4b73b4c629427628d01f6b0bed6a127fc76bb2a45ac3fe",
         "item_id":"token_transfer_0x162d1978aa9b321676eae6c4df2b3fe44971431ea5a4e4a639ea43e5280b2091_150",
         "item_timestamp":"2023-04-21T11:43:59Z"
      }
   }
}

{
   "subscriptionId":"38",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/tokentransfer"
   },
   "eventType":"TOKEN_TRANSFER",
   "createdAt":"2023-04-21T11:45:40.636Z",
   "event":{
      "targetAddress":"0x60e4d786628fea6478f785a6d7e704777c86a7c6",
      "message":{
         "type":"token_transfer",
         "token_address":"0x60e4d786628fea6478f785a6d7e704777c86a7c6",
         "from_address":"0xf563af5162b1e6d49e46c2435da275a034f301a5",
         "to_address":"0x1b57d440351f566ab96d90d606dd2b4f96dbe864",
         "value":29037,
         "transaction_hash":"0x74802adddbc4696173bda9358dffb95e88212bd3b66930aa80fe69b5dbb7762a",
         "log_index":296,
         "block_number":17094593,
         "block_timestamp":1682078015,
         "block_hash":"0xc8b32258ea16ae50cc1e8abd3df5799e81a29483ae881423b8049506a1e7e475",
         "item_id":"token_transfer_0x74802adddbc4696173bda9358dffb95e88212bd3b66930aa80fe69b5dbb7762a_296",
         "item_timestamp":"2023-04-21T11:53:35Z"
      }
   }
}

BELOW_THRESHOLD_BALANCE

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

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

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: "55",
    description: "TEST_DESCRIPTION",
    protocol: "ETHEREUM",
    network: "MAINNET",
    notification: {
        webhookUrl: "https://webhook.test.server/balance",
    },
    eventType: "BELOW_THRESHOLD_BALANCE",
    createdAt: "2023-04-25T07:06:01.193Z",
    event: {
        message: {
            type: "belowThresholdBalance",
            address: "0xBA826fEc90CEFdf6706858E5FbaFcb27A290Fbe0",
            threshold: "3932198180400855840",
            balance: "293219818040085584"
        }
    }
}

BLOCK_PERIOD, NEW_HEADS

eventType값을 BLOCK_PERIOD 또는 NEW_HEADS 로 설정하는 경우, 사용 가능한 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": "TOKEN_TRANSFER",
    "notification": {
        "webhookUrl": "https://webhook.test.server/block"
    },
    "condition": {
        "period":3
    }
}'

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

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

{
   "subscriptionId":"312",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/block"
   },
   "eventType":"BLOCK_PERIOD",
   "createdAt":"2023-04-21T09:46:26.419Z",
   "event":{
      "period":1,
      "message":{
         "type":"block",
         "number":17093961,
         "hash":"0x79571a418b617b59739066761d7368d3287bae0a40d2a19494d12a9174c7e513",
         "parent_hash":"0x7808bafa70cb77641231881ca7793687e3e36b669a10a36fad90bb8c21b0ee48",
         "nonce":"0x0000000000000000",
         "sha3_uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
         "logs_bloom":"0x99a14b3f51101616720552aca1304abba4e07d225c541a1030ab82973f88e6a4700677c0c5940d20e1d39b5bc6222f4406d7d0618a653be52774402315aca91924a2c11edd0e5cad2f8b56ab4a18a4e401bdaa0064459f1817396cd5dce0080e1a795b58b2026583165610882c728fcd6031f66daa30ae0c93ad77da055f82745c0183f07808ab0c06f484ab328ae4064c2b30c1c14909d9687b68df70f31a38eabb19404930ef4b9a1e58e23d930e8745c65288f986703bd7715dc2048acc4953aa4c12744788e815841b18a6efb224c76e460657682ab93a16a62ae251685b55fabe299d848cdd3a8cf7a85001323b9437801971a81b74001d7f0db269bdc5",
         "transactions_root":"0x0750e5d04fffd3b95f229bb52c5bc495e3c2516bf21c679c391c023703b4da7d",
         "state_root":"0xb0eed3120001d3b24f60ddc432d3cba138a9291bafd7766a214ca82be58b0499",
         "receipts_root":"0xe954eb9564cb99064378c6322db2e2ca01a2da23b03cbd0770a48d255df5f646",
         "miner":"0x1f9090aae28b8a3dceadf281b0f12828e676c326",
         "difficulty":0,
         "total_difficulty":5.875000371659836e+22,
         "size":99457,
         "extra_data":"0x7273796e632d6275696c6465722e78797a",
         "gas_limit":30000000,
         "gas_used":20054486,
         "timestamp":1682070275,
         "transaction_count":131,
         "base_fee_per_gas":34295746100,
         "item_id":"block_0x79571a418b617b59739066761d7368d3287bae0a40d2a19494d12a9174c7e513",
         "item_timestamp":"2023-04-21T09:44:35Z"
      }
   }
}

{
   "subscriptionId":"312",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/block"
   },
   "eventType":"NEW_HEADS",
   "createdAt":"2023-04-21T09:46:26.419Z",
   "event":{
      "period":1,
      "message":{
         "type":"block",
         "number":17094685,
         "hash":"0xf8ae974622cbb1647c6a5b192546a7d5fc096b85da6c482994cdb845f2bcc9f1",
         "parent_hash":"0x14b07b821381b446b36abe8c2e50abb8ec503fb8cb68b7361807f26d1917d846",
         "nonce":"0x0000000000000000",
         "sha3_uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
         "logs_bloom":"0x0423220065084a9c912908bac3510323d0e8548a0e52a488028913b0d0aa003145981dd0634820343b1d15046bc1210023038008da2fb90111008998112c60c000207488d76019602adb4e4fb86b823a9420410409c408d416522596cac231244b2228115343651101cd966402445c6d3068490d00d52612822a879028632004608182f4d1008005244888c083b644b000021c8dbb0b69cae432514e22301280ae08410615c0e00822e2e4f5299c840566c8085944c8a9c2b190241a002288dd69391052030882cb968887a32440e05448c8074280cab0534654111218a0e44401b26798c18398a6221700e00e0068ad0a4c12189129c24201b9b889c2a1d405",
         "transactions_root":"0xdb93adcb14e3818ccaf8b6edb456b86fdab7be5a4cbd729ee63b107823b5896f",
         "state_root":"0x3c1d6405575b4e3af992aede0ff97aacd38af38d6fc1e2cd448826a6e1725dcd",
         "receipts_root":"0x20665e75d4a95074c3b0635613f95f253ce9362ca6233e0e9e02deca21a0799b",
         "miner":"0xba401cdac1a3b6aeede21c9c4a483be6c29f88c5",
         "difficulty":0,
         "total_difficulty":5.875000371659836e+22,
         "size":166552,
         "extra_data":"0x6279206275696c64657230783639",
         "gas_limit":30000000,
         "gas_used":11251331,
         "timestamp":1682079119,
         "transaction_count":115,
         "base_fee_per_gas":38912382163,
         "item_id":"block_0xf8ae974622cbb1647c6a5b192546a7d5fc096b85da6c482994cdb845f2bcc9f1",
         "item_timestamp":"2023-04-21T12:11:59Z"
      }
   }
}

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: "47",
  description: "TEST_DESCRIPTION",
  protocol: "ETHEREUM",
  network: "MAINNET",
  notification: {
    webhookUrl: "https://webhook.test.server/blocklist",
  },
  eventType: "BLOCK_LIST_CALLER",
  createdAt: "2023-04-24T06:29:01.263Z",
  event: {
    targetAddress: "0x5e4e65926ba27467555eb562121fac00d24e9dd2",
    blockListCaller: "0x6887246668a3b87f54deb3b94ba47a6f63f32985",
    message: {
      type: "trace",
      transaction_index: 121,
      from_address: "0x6887246668a3b87f54deb3b94ba47a6f63f32985",
      to_address: "0x5e4e65926ba27467555eb562121fac00d24e9dd2",
      value: 0,
      input: "0xd0f893440005969e4300007800000600000000000000000000000000000000000022000000006446211b00010524c2000007000000006446212a00010524c2000046000000006446212a00010524c400000700000000644621390001...d3307040000ffff6f084e9a",
      output: "0x",
      trace_type: "call",
      call_type: "call",
      reward_type: null,
      gas: 163541,
      gas_used: 81402,
      subtraces: 10,
      trace_address: [0],
      error: null,
      status: 1,
      transaction_hash: "0x291d2fdfa11284604e07861a1986633c4e05c5ca6a7914cbd1f7c52578a6a319",
      block_number: 17114360,
      trace_id: "call_0x291d2fdfa11284604e07861a1986633c4e05c5ca6a7914cbd1f7c52578a6a319_",
      trace_index: 555,
      block_timestamp: 1682317631,
      block_hash: "0x436275b331c34eba47dace47ae8f6718e0aeea245eb17c5ee87bca517ded4018",
      item_id: "trace_call_0x291d2fdfa11284604e07861a1986633c4e05c5ca6a7914cbd1f7c52578a6a319_",
      item_timestamp: "2023-04-24T06:27:11Z"
    }
  }
}

{
  subscriptionId: "46",
  description: "TEST_DESCRIPTION",
  protocol: "ETHEREUM",
  network: "MAINNET",
  notification: {
    webhookUrl: "https://webhook.test.server/allowlist"
  },
  eventType: "ALLOW_LIST_CALLER",
  createdAt: "2023-04-24T06:15:43.442Z",
  event: {
    targetAddress: "0x5e4e65926ba27467555eb562121fac00d24e9dd2",
    allowListCaller: "0x6887246668a3b87f54deb3b94ba47a6f63f32985",
    message: {
      type: "trace",
      transaction_index: 127,
      from_address: "0x6887246668a3b87f54deb3b94ba47a6f63f32985",
      to_address: "0x5e4e65926ba27467555eb562121fac00d24e9dd2",
      value: 0,
      input: "0xd0f8934400059691b500005d0000060000000000000000000000000000000000000a0000000064461e0000010524800000020000000064461e0f00010524800000440000000064461e0f0001052481...020000ffff63817e3e",
      output: "0x",
      trace_type: "call",
      call_type: "call",
      reward_type: null,
      gas: 153352,
      gas_used: 81402,
      subtraces: 10,
      trace_address: [0],
      error: null,
      status: 1,
      transaction_hash: "0x5923e673d1ab6d785cbb9780cc125bb0e622a69f36d7623e513e7fde49509609",
      block_number: 17114294,
      trace_id: "call_0x5923e673d1ab6d785cbb9780cc125bb0e622a69f36d7623e513e7fde49509609_",
      trace_index: 440,
      block_timestamp: 1682316839,
      block_hash: "0xbc7cb0f777f6a83b6e19bb56abc30a02362d308f90426747bf1cd03d45cd638f",
      item_id: "trace_call_0x5923e673d1ab6d785cbb9780cc125bb0e622a69f36d7623e513e7fde49509609_",
      item_timestamp: "2023-04-24T06:13:59Z"
    }
  }
}

LOG

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

Key	Type	Required	Description	Example Value
address	String	true	모니터링 대상 컨트랙트의 주소(CA)	"0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B"
topics	Array of String	true	모니터링 하고자 하는 LOG의 토픽 목록	[ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0x00000000000000000000000056178a0d5f301baf6cf3e1cd53d9863437345bf9", "0x00000000000000000000000060594a405d53811d3bc4766596efd80fd545a270"]

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/log"
    },
    "condition": {
        "address": "0x7d03C4d82b562993A4e12c26cBBd32f499c37F9B",
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x00000000000000000000000056178a0d5f301baf6cf3e1cd53d9863437345bf9",
          "0x00000000000000000000000060594a405d53811d3bc4766596efd80fd545a270",
        ]
    }
}'

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

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

{
   "subscriptionId":"45",
   "description":"TEST_DESCRIPTION",
   "protocol":"ETHEREUM",
   "network":"MAINNET",
   "subscriptionType":"WEBHOOK",
   "notification":{
      "webhookUrl":"https://webhook.test.server/log"
   },
   "eventType":"LOG",
   "createdAt":"2023-04-21T12:35:53.592Z",
   "event":{
      "targetAddress":"0x388c818ca8b9251b393131c08a736a67ccb19297",
      "topics":[
         {
            "0":"0x27f12abfe35860a9a927b465bb3d4a9c23c8428174b83f278fe45ed7b4da2662"
         }
      ],
      "message":{
         "type":"log",
         "log_index":235,
         "transaction_hash":"0xfe155f13828ed5c78ee2383b4b46511d37060eb4285cf279a145442cc1dc7f76",
         "transaction_index":95,
         "address":"0x388c818ca8b9251b393131c08a736a67ccb19297",
         "data":"0x00000000000000000000000000000000000000000000000000a72dd5bccf60d7",
         "topics":[
            {
               "0":"0x27f12abfe35860a9a927b465bb3d4a9c23c8428174b83f278fe45ed7b4da2662"
            }
         ],
         "block_number":17094796,
         "block_timestamp":1682080451,
         "block_hash":"0x07d99eef082bc70ef98b75f5e639f7fe3928d3aa5ce711f1c1a894e713a2b8b2",
         "item_id":"log_0xfe155f13828ed5c78ee2383b4b46511d37060eb4285cf279a145442cc1dc7f76_235",
         "item_timestamp":"2023-04-21T12:34:11Z"
      }
   }
}