Webhook 사용 예제
1. 환경 세팅
1-1. Nodit 콘솔 가입
Nodit에서는 다양한 블록체인 네트워크에 연결할 수 있는 Node 서비스를 제공합니다. 아래 링크를 클릭하여 Nodit Console에 접속하여 회원가입을 진행하세요.
1-2. 원하는 노드 연결하기
회원가입이 완료되었다면, Nodes 페이지에서 사용하고 싶은 체인의 노드를 연결해주세요.
1-3. Webhook Listener Endpiont 얻기
webhook 생성을 위해서는 알림을 받을 별도의 Webhook Listener 서버가 필요합니다. 이 서버는 외부의 이벤트 통지를 받아 처리하는 역할을 합니다. 서비스 운영을 위해서는 Webhook Listener 서버를 직접 구축해야 하지만, 이번 예제에서는 webhook 응답만 확인하기 때문에 써드파티 서비스를 활용합니다.
[써드파티 서비스 사용 예시]
-
Postman Mockserver: Postman Mockserver를 사용하면 API를 모의할 수 있으며, Webhook 요청을 받을 수 있는 임시 URL을 제공받습니다. 설정은 간단하며, Postman의 Mock 서버 생성 기능을 통해 쉽게 구성할 수 있습니다. 자세한 설정 방법은 아래 링크에서 확인할 수 있습니다.
▶︎ Set up Postman Mock server -
Webhook.site: Webhook.site는 실시간으로 Webhook 데이터를 캡처하고 확인할 수 있는 서비스를 제공합니다. 이 서비스를 사용하면 별도의 서버 구축 없이 즉시 Webhook 테스트를 시작할 수 있습니다. 아래 링크를 클릭하면 무료 사용할 수 있는 Webhook Listener Endpoint를 얻을 수 있습니다.
▶︎ Webhook.site
이번 예제에서는 Webhook.site를 활용하여 Webhook 응답을 확인합니다. Webhook.site에 접속하여 제공되는 unique URL을 복사합니다.
webhook.site 화면
2. Webhook 생성하기
콘솔 혹은 Webhook API를 사용하여 원하는 이벤트를 구독할 수 있습니다. 이 예제에서는 Webhook API를 활용하여 BLOCK_PERIOD 이벤트를 구독하는 Webhook을 생성합니다.
- X-API-KEY: Nodit 콘솔에서 제공된 실제 API 키를 입력합니. API 키는 서비스에 안전하게 접근하고, 사용자의 인증을 확인하는 데 필수적인 요소입니다.
- webhookUrl: 구독하고자 하는 이벤트의 알림을 받을 Webhook Listener Endpoint를 입력합니다. 위에서 복사한 Webhook Listener Endpoint를 webhookUrl에 붙여넣습니다.
curl --request POST \
--url https://web3.nodit.io/v1/ethereum/mainnet/webhooks \
--header 'X-API-KEY: {Your API key}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"eventType": "BLOCK_PERIOD",
"description": "Webhook Test",
"notification": {
"webhookUrl": "{Your webhook listener endpoint}"
},
"condition": {
"period": 1
}
}
'
위의 스크립트를 실행하고 webhook이 성공적으로 생성되면, 성공 메세지와 함께 subscription ID을 포함한 응답을 반환합니다. 아래는 생성 예시입니다.
{
"subscriptionId": "2361",
"description": "Webhook test",
"protocol": "ETHEREUM",
"network": "MAINNET",
"eventType": "BLOCK_PERIOD",
"notification": {
"webhookUrl": "https://example.com/webhook"
},
"signingKey": "cd5...d12",
"condition": {
"period": 1
},
"createdAt": "2024-04-29T08:04:11.098Z"
}
3. Webhook Listener 서버에서 응답 확인하기
Webhook이 정상적으로 생성되면, 구독하는 이벤트가 발생할 때마다 Webhook Listener 서버에 알림을 전송합니다. 아래는 Webhook.site에서 알림을 받은 예시입니다.
{
"subscriptionId": "2347",
"description": "Webhook test",
"protocol": "ETHEREUM",
"network": "MAINNET",
"subscriptionType": "WEBHOOK",
"notification": {
"webhookUrl": "https://webhook.site/c3aa6f3b-e19d-416c-ab24-2659ffc0f304"
},
"signingKey": "0dc...286",
"eventType": "BLOCK_PERIOD",
"event": {
"period": 5,
"message": {
"parent_hash": "0x4cff8863b4dadd17424574f71898d46dc4170567e68fece6514c3c0fd3c6aa37",
"sha3_uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"miner": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
"state_root": "0x0ac76dcf2b9b460db6aa1b87aba041a16fdc626d454c6c8722753a54a4180684",
"transactions_root": "0x6504d7b34c36760e9de9c8ab5468c71f9442aab965a29234822651557b076a83",
"receipts_root": "0x9b7bebea2e5bdc0055e1b937e6993cc6b52a533ce68373b6e91b61bd4d2b570d",
"logs_bloom": "0xbffffdfdfff7ffff7fdfffefdffffffffdbbffffcfffffffaffffff7feffffffffffffedf7cfffdf7fefff7ffffbfddfbfffef6ffbfdfffdfffbfc3df3bffffbffefbffbff6fffefffaf67fffef7fffefffff7f7ffffffff9fffffefeffffffffbffefff7afff5f7f7fffffffbbdfbff9fbffefb9ffdffeffffdfffbffffdafffefefbdffdffff7ef8fdfffbffffffffffbfdfbf7ff6f7fffffbebefffdfffffbeffdfff9fdfef7fafffffffffffffefbeffffffffffffffffdffffdbfe7fbfff7fdffffbfffcfdb7fffffffbffffbffffbffffefffddffff7fefffadffffffbfffffffffffffdeffbedfdf7bf1fbdffafffffefffdffffff7fdfffeffbffffd",
"difficulty": "0",
"gas_limit": 30000000,
"gas_used": 29997074,
"extra_data": "0x6265617665726275696c642e6f7267",
"mix_hash": "0xd7af35f660850b15564a7667678d51a9db1bbe045702efbb2b8034d98b01c2f4",
"nonce": "0x0000000000000000",
"hash": "0xd69b6a597874ad7382569e85b93bed4e8d0d6c7152b9ac59677611fa00a568a6",
"size": 155824,
"total_difficulty": "58750003716598352816469",
"transactions": [
"0xef99067235b9d30831f5161cdfb9cd1a1b24f04fc9a694b120ef8e568bd70234",
// ... snip
"0x586442f7566519e7e3f026bfd318a65f559783cafe0f5a9b3162dc7f50c0d6cb"
],
"transaction_count": 318,
"log_count": 1548,
"base_fee_per_gas": 5838584039,
"withdrawals_root": "0xc0419b57a2665a2682834b323193cdbc56f13698aed0467a028b586ae9720488",
"withdrawal_count": 16,
"blob_gas_used": "0x0",
"excess_blob_gas": "0x60000",
"parent_beacon_block_root": "0x40735f721e4de4c63825f5885795ade7ac314a8502953ef14c074b64b70b2b4e",
"type": "block",
"number": 19758850,
"timestamp": 1714368119
}
},
"createdAt": "2024-04-29T05:23:46.838Z"
}
Kaia Webhook 데이터에 대하여
Kaia 체인에서 Webhook을 사용하는 경우 Webhook의 payload 구조 및 일부 필드의 형식이 다른 이더리움 계열 체인의 데이터와 상이할 수 있습니다. 이는 체인별로 정의된 고유한 데이터 명세를 유지하기 위한 것으로, Kaia Webhook 데이터는 노드의 kaia namespace에 속한 API 응답 데이터를 기준으로 생성됩니다. 예를 들어, 트랜잭션 관련 Webhook payload의 transaction_type 필드는 Kaia와 이더리움에서 아래와 같이 상이한 형식의 값으로 반환됩니다.
- 이더리움의
transaction_type: 2 (Number 타입)- Kaia의
transaction_type: "TxTypeEthereumDynamicFee" (String 타입)
4. Webhook 수정 및 조회하기
이제 등록한 Webhook을 수정해본 뒤, 영구적으로 삭제하는 방법을 알아보겠습니다.
Nodit Webhook 서비스에는 알림을 일시 정지할 수 있는 기능을 제공하고 있습니다. 일시정지를 한 경우, 등록한 Webhook은 삭제되지 않고 알림만 해제된 상태가 됩니다. 아래의 예제 스크립트를 실행하여 isActive 필드를 false로 설정해보세요. (이때, 유효한 SUBSCRIPTION_ID와 YOUR_API_KEY를 입력해야 합니다.)
curl --request PATCH \
--url https://web3.nodit.io/v1/ethereum/mainnet/webhooks/{SUBSCRIPTION_ID} \
--header 'X-API-KEY: {YOUR_API_KEY}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"isActive":false
}'
result가 true라는 응답을 반환하면 수정이 성공적으로 진행되었음을 의미합니다.
{
"result": true
}
이번엔 수정된 내용을 확인하기 위해 Webhook 정보를 조회합니다. (이때, 유효한 SUBSCRIPTION_ID와 YOUR_API_KEY를 입력해야 합니다.)
curl --request GET \
--url 'https://web3.nodit.io/v1/ethereum/mainnet/webhooks?subscriptionId={SUBSCRIPTION_ID}' \
--header 'X-API-KEY: {YOUR_API_KEY}' \
--header 'accept: application/json'
{
"total": 1,
"rpp": 10,
"page": 1,
"items": [
{
"subscriptionId": "2361",
"description": "webhook Test",
"environmentId": "9999999999999999999",
"protocol": "ETHEREUM",
"network": "MAINNET",
"subscriptionType": "WEBHOOK",
"eventType": "BLOCK_PERIOD",
"notification": {
"webhookUrl": "https://example.com/webhook"
},
"signingKey": "0a2...2fd",
"isActive": false,
"updatedAt": "2024-04-29T08:20:20.000Z",
"createdAt": "2024-04-29T08:17:21.826Z",
"condition": {
"period": 1
}
}
]
}
5. Webhook 삭제하기
마지막으로 구독 중인 Webhook을 삭제해보겠습니다. 단, 한 번 삭제를 진행하면 되돌릴 수 없기 때문에 신중하게 삭제 작업을 결정해야 합니다. 삭제 과정은 해당 Webhook에 대한 모든 설정과 데이터 전송을 중지시키므로, 이 이상 이벤트 알람을 받지 못하게 됩니다. 아래 예제 스크립트를 이용하여 이번 예제에서 생성한 Webhook을 삭제해보세요.
curl --request DELETE \
--url https://web3.nodit.io/v1/ethereum/mainnet/webhooks/{SUBSCRIPTION_ID} \
--header 'X-API-KEY: {YOUR_API_KEY}' \
--header 'accept: application/json'
result가 true라는 응답을 반환하면 삭제가 성공적으로 진행되었음을 의미합니다.
{
"result": true
}
Webhook Retry 정책
Nodit Webhook은 현재 최대 1번의 Retry를 지원합니다. webhookUrl 호출 후 200 OK 응답을 받지 못한 경우, 최초 요청 시점으로부터 15초 후 Webhook 데이터 전달을 위한 재호출이 실행됩니다.