Webhook Quickstart

Webhook 서비스 안내


Webhook이란 무엇인가요?

Webhook이란 온체인 이벤트 발생을 실시간으로 전달받을 수 있 개발 도구입니다. 블록체인 트랜잭션은 비동기 방식으로 동작하기 때문에, Webhook과 같은 Notification 또는 구독 기능은 DApp 개발에 필수 요소라고 할 수 있습니다. 개발자가 모니터링 하고자 하는 온체인 이벤트를 정의한 뒤 이를 Webhook으로 등록하면, 해당 조건에 맞는 이벤트 발생 시 Webhook 등록 시 지정한 Listener Endpoint로 해당 이벤트 상세 정보를 전달받을 수 있습니다. 조건을 세분화 한 여러 Webhook을 등록할 수 있으며, 이를 활용하여 DApp 구현시 실시간 반응형 UI 또는 사용자 알림 기능을 구현할 수 있습니다.


Usecases

다음은 루니버스 Webhook을 활용한 몇가지 어플리케이션 구현 시나리오 예제입니다. Webhook에서 구독 가능한 데이터를 확인하고 더 많은 활용 방법을 찾아보세요.

  • 사용자가 제출한 트랜잭션이 성공적으로 처리되면 Webhook으로 트랜잭션 Receipt를 받아 화면에 업데이트 할 수 있습니다.
  • 사용자 지갑의 잔고가 일정 수치 이하로 떨어지면 알림을 받아 사용자에게 토큰 구매를 요청할 수 있습니다.
  • 사용자의 지갑 주소 또는 특정 컨트랙트 주소에 이벤트(자산 전송, 트랜잭션 전송 등) 발생시 사용자에게 알람을 전송하거나 적절한 후처리 액션을 수행할 수 있습니다.
  • 블록이 생성될 때마다 알림을 받음으로서 특정 네트워크 환경이 안정적으로 동작하고 있는지 모니터링 할 수 있습니다.

Webhook으로는 어떤 이벤트 및 데이터를 구독할 수 있나요?

루니버스 Webhook으로 구독할 수 있는 이벤트 및 데이터에 대한 명세는 Webhook Types페이지에서 확인하실 수 있습니다.

현재 Webhook은 API를 통한 생성, 조회, 수정, 삭제만 지원합니다. 관련 API 명세는 Webhook API 페이지를 참고해주세요. 추후 업데이트를 통해 콘솔 메뉴에서 Webhook을 관리할 수 있도록 지원할 예정입니다.


Webhook 지원 체인

NetworkSupporting
Ethereum Mainnet:white-check-mark:
Ethereum Testnet (goerli):white-check-mark:
Ethereum Testnet (sepolia):white-check-mark:
Ethereum Testnet (holesky):white-check-mark:
Polygon Mainent:white-check-mark:
Polygon Testnet (mumbai):white-check-mark:
Arbitrum Mainnet:white-check-mark:
Arbitrum Testnet (goerli):white-check-mark:
Arbitrum Testnet (sepolia):white-check-mark:
Optimism Mainnet:white-check-mark:
Optimism Testnet (goerli):white-check-mark:
Optimism Testnet (sepolia):white-check-mark:

Webhook 사용 방법

Webhook 연동은 크게 아래 네 단계로 진행됩니다.

  1. Webhook Listener Endpoint 구현하기
  2. createWebhook API 호출하여 Webhook 생성하기
  3. 구현된 Notification URL로 Webhook Event의 정상 수신 확인하기
  4. Webhook 수정 또는 삭제하기

1. Webhook Listener Endpoint 구현하기

가장 먼저, Webhook 생성 및 수정 API 호출 시 요청 Body에 포함되는 notification.webhookurl 필드에 입력할 listener endpoint 생성이 필요합니다. Listener endpoint는 이벤트 발생시 루니버스 Web3 Engine으로부터 발생되는 요청을 받아 처리해야 합니다. 사용자는 Listener endpoint 제공을 위한 별도의 서버를 구축하거나 또는 Slack과 같은 어플리케이션의 Webhook URL 생성 기능을 사용하여 연동할 수 있습니다.

❗️

Listener Endpoint는 모든 POST 요청에 대해 200 OK로 응답해야 합니다.

Listener Endpoint는 개발자의 선호에 따라 다양한 방식으로 구현 또는 제공될 수 있습니다. 유일한 제약사항은, 모든 Listener Endpoint는 유입되는 POST 요청에 대해 항상 Http Status Code 200 OK로 응답해야 한다는 것입니다. 200 OK 이외의 다른 응답 코드가 반환되는 경우, 루니버스 서버는 이를 비정상적인 Endpoint로 판단하여 요청을 반복적으로 재시도하거나 Webhook 목록에서 예고 없이 제거할 수 있습니다.

본 페이지에서는 Webhook Listener Endpoint를 간단하게 구현 및 테스트하기 위한 몇가지 방법을 아래와 같이 제시합니다.

(1) 테스트를 위한 3rd Party App 사용하기 - Postman

Postman 공식 홈페이지에 접속한 뒤 사용중인 OS에 적합한 어플리케이션 버전을 다운로드 받아 설치합니다. 어플리케이션을 실행하면 보여지는 좌측 메뉴에서 'Mock Servers'를 클릭하여 진입하면, 위와 같이 Mock 서버 내에 원하는 URL Path를 생성할 수 있는 화면이 보여집니다.

Webhook에 사용할 URL을 생성하기 위해 Request Method를 POST로 선택하고, 생성하고자 하는 URL을 path로 입력한 뒤 Response Code를 200으로 설정합니다. 이는 모든 요청에 대해 200 OK로 상태코드를 응답하기 위함입니다.

[Next] 버튼을 클릭한 뒤 Mock 서버 이름을 입력하여 서버 생성을 완료합니다. Mock 서버 생성이 완료되면, 아래 화면과 같이 해당 서버의 URL이 생성됩니다.

이제 해당 URL Path에 POST 요청에 설정한 하위 Path를 붙여 Webhook Listener Endpoint URL로 사용할 수 있습니다. Webhook 등록 이후 이벤트가 발생하여 루니버스 서버로부터 요청이 전송되는 경우 아래와 같이 Mock Server 페이지에서 인입된 요청 목록 및 상세 항목을 확인하실 수 있습니다.

(2) 서버 구축하기

Listener Endpoint를 제공하는 가장 기본적인 방법은 DApp과 연동된 서버 내에서 Webhook 수신을 위한 Endpoint를 별도로 구현하여 제공하는 방법입니다. 사용중인 개발 환경 및 프레임워크에 따라 간단한 Endpoint를 생성하는 방법은 다양합니다. 본 문서에서는 Express를 활용하여 Javascript로 간단한 Endpoint를 구현하기 위한 아래 코드를 예제로 제공합니다.

import express, { Request, Response, NextFunction } from 'express';

async function main(): Promise<void> {
  const app = express();	
  app.post('/webhook-test', (req: Request, res: Response, next: NextFunction) => {
    const webhookEvent = req.body;
    console.log(`Webhook Body: ${webhookEvent.body}`);
    res.send("SUCCESS");
  });	

  app.listen('8000', () => {
    console.log(`App listening 127.0.0.1:8000`);
  });
}
main();

(3) Slack 등 플랫폼에서 제공하는 webhook URL 활용하기

다양한 어플리케이션 서비스에서는 Webhook을 받아 처리할 수 있도록 Webhook URL을 생성해주는 기능을 제공하고 있습니다. 개발자들이 주로 사용하는 모니터링 플랫폼이나, Slack과 같은 협업 프로그램의 Webhook URL 생성 기능을 활용하여 특정 온체인 이벤트 발생시 이를 메시지나 다른 형태로 전달받을 수 있습니다. Slack에서 Webhook URL을 생성 및 연동하여 채널로 받는 방법은 Slack Webhook 생성 가이드 문서를 참고해주세요.


2. createWebhook API 호출하여 Webhook 생성하기

Webhook Types 페이지의 각 Type 별 Webhook 생성 예제를 참고하여, Webhook을 생성하세요. 이때 notification.webhookurl 필드에는 1에서 생성한 Listener Endpoint URL을 입력해야합니다. 아래는 이더리움 메인넷 환경에서 BLOCK_PERIOD 타입의 Webhook을 생성하는 기본적인 예제 요청입니다.

curl --location --request POST 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "TEST",
    "eventType": "BLOCK_PERIOD",
    "notification": {
        "webhookUrl": "https://f139f9e4-9ed...c8.mock.pstmn.io/webhook-test"
    },
    "condition": {
			"period":1
		}
}'

3. 구현된 Notification URL로 Webhook Event의 정상 수신 확인하기

Webhook이 정상적으로 생성되면, 1에서 구축한 Listener Endpoint로 Event 요청이 전달됩니다. Postman을 활용한 경우 Mock servers 요청 목록에 정상적으로 요청이 인입되는지 확인하세요. 자체 서버를 구축한 경우 요청에 대한 콘솔 로그를 확인하고, Slack과 같은 플랫폼에 연동한 경우 해당 채널에 정상적으로 메시지가 전달되는지 확인하실 수 있습니다.


4. Webhook 수정 또는 삭제하기

이제 등록한 Webhook을 수정해본 뒤, 영구적으로 삭제하는 방법을 알아보겠습니다.

2의 예시에서 등록한 BLOCK_PERIOD Webhook을 잠시 Disable하기 위해 아래와 같이 isActive 필드를 false로 설정하여 updateWebhook 요청을 전송해보겠습니다.

curl --location --request PATCH 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks/{SUBSCRIPTION_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "isActive": false
}'

업데이트 이후, 블록 주기에 따라 지속적으로 인입되던 Webhook 요청이 비활성화 되어 메시지가 전달되지 않아야 합니다.

Webhook이 더이상 필요없게 된 경우, 아래와 같은 deleteWebhook API 호출을 통해 Webhook을 삭제할 수 있습니다.

curl --location --request DELETE 'https://web3.luniverse.io/v1/ethereum/mainnet/webhooks/{SUBSCRIPTION_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json'