Webhook

Key Features

✅ Real-time On-chain Notification
블록, 트랜잭션, 이벤트, 스마트 컨트랙트의 상태 변화 등 어플리케이션에서 필요한 온체인 이벤트를 실시간으로 구독 할 수 있습니다. 데이터 조회를 매번 요청하거나 Stream 채널을 유지하지 않고 비동기 API 호출을 통한 데이터 조회가 필요하다면 Webhook을 활용한 효과적인 모니터링이 가능합니다.

✅ Endpoint Registration
정의한 이벤트가 발생하는 경우 관련 데이터를 수신할 Endpoint URL을 직접 지정할 수 있으며, 이를 통해 맞춤형 애플리케이션 워크플로우를 설계할 수 있습니다.

✅ Filter Support
트랜잭션, 블록, 이벤트 등 다양한 필터를 활용하여 효과적으로 대상을 모니터링하고, 다양한 조건의 데이터를 각각 다른 Endpoint로 등록하여 수신하는 등의 응용을 통해 복잡한 비즈니스 로직을 쉽게 구현할 수 있습니다.

실시간 온체인 이벤트 Notification, Webhook

Nodit Webhook은 정의한 온체인 이벤트가 발생할 때, Webhook에 등록된 URL로 이벤트의 발생 정보를 전달함으로서 실시간 이벤트에 대한 반응형 어플리케이션을 구현할 수 있도록 돕는 개발도구입니다. 블록체인에서 새로운 트랜잭션이 발생하거나 스마트 컨트랙트 상태가 변경되는 등 중요한 이벤트가 발생할 때, 실시간으로 정보를 받아볼 수 있습니다.

Webhook은 특정 이벤트가 발생할 때 지정된 URL(사용자 Endpoint)로 HTTP POST 요청을 자동으로 전송합니다. 이 요청에는 이벤트의 유형, 관련 데이터, 기타 필요한 정보가 포함됩니다. Webhook의 기본 작동 흐름은 다음과 같습니다:

• 이벤트 발생: 블록체인에서 새로운 트랜잭션, 블록 생성, 또는 스마트 컨트랙트 상호작용과 같은 이벤트가 발생합니다.
• 트리거(Trigger): 해당 이벤트에 의해 Webhook이 트리거됩니다.
• 데이터 전송: Webhook은 발생한 이벤트 데이터를 포함한 HTTP POST 요청을 사용자 지정 Endpoint로 자동 전송합니다.

Webhook Quickstart

구독할 이벤트를 정의하고 Webhook을 수신할 Endpoint를 등록하여 Webhook을 생성해볼까요? Webhook은 다음과 같이 Nodit 콘솔의 Webhook 메뉴를 통해 생성하거나 API를 통해 생성할 수 있습니다.

Nodit 콘솔을 통한 Webhook 생성 및 관리

Webhook 생성하기

Nodit 콘솔의 Webhook 메뉴에서 새로운 Webhook을 생성할 수 있습니다. Select Networks 영역에서 이벤트를 대상 체인을 선택하고 Select Event Type영역에서 구독하고자 하는 이벤트 타입을 선택합니다. 이벤트가 발생하는 경우 데이터를 수신하기 위한 Webhook URL을 입력한 뒤 [Test Webhook] 버튼을 클릭하여 해당 URL에서 정상적으로 메시지 수신이 가능한지 테스트할 수 있습니다. 이후 선택한 Event Type에 따라 필요한 데이터를 우측 Conditions 영역에서 설정함으로서 Webhook 생성을 완료할 수 있습니다.

🚀

Instant Webhook 옵션을 새롭게 지원합니다.

2025년 5월 30일부터 새롭게 지원되는 Instant Webhook 옵션은 모니터링 대상 이벤트가 포함된 블록의 확정 여부와 상관 없이, Nodit 노드에서 해당 이벤트가 감지되는 즉시 Webhook 메시지를 수신할 수 있는 옵션입니다. 이벤트의 확정(Confirmation) 여부 보다는 이벤트 발생에 대한 즉각적인 반응과 신속한 알림이 필요한 프로젝트에 적합합니다. 사용자 액션 트래킹, UI 반응 개선, 선제적 리스크 탐지 등과 같이 빠른 피드백이 중요한 애플리케이션에서 효과적으로 활용할 수 있습니다.

Instant Webhook 옵션을 비활성화하면 기존 Webhook과 동일하게 이벤트 트랜잭션이 포함된 블록이 확정된 이후에만 메시지가 발송됩니다. 블록이 롤백되거나 재구성되는 경우 이벤트가 최종적으로 발생하지 않았을 수도 있으므로, 데이터 확정성이 중요한 경우에는 옵션 비활성화를 통해 기존 방식의 Webhook을 사용하는 것을 권장합니다.

💡 API를 사용하여 Webhook을 생성 또는 조회하는 경우 isInstant 필드를 true 또는 false로 설정하여 옵션을 활성화/비활성화 할 수 있습니다.

Webhook 목록 확인 및 관리하기

Webhook 생성이 완료되면 Webhook 목록에서 생성된 Webhook의 ID, 네트워크, Event Type, 생성일자, 상태, Signing Key 정보를 확인할 수 있습니다. Webhook의 상태는 다음과 같이 분류됩니다.

• 활성화 상태(Enabled): Webhook에 정의된 이벤트 모니터링이 동작하는 상태이며, Webhook 메세지를 수신할 수 있습니다.
• 비활성화 상태(Disabled): Webhook 이벤트 모니터링이 비활성화되어 Webhook 메세지를 수신할 수 없는 상태입니다.

토글 버튼을 클릭하여 Webhook의 상태를 변경함으로써 Webhook 메세지 수신을 잠시 멈추거나 재개할 수 있습니다. 또한 각 항목의 휴지통 아이콘을 클릭하여 불필요한 Webhook을 삭제할 수 있습니다. 삭제한 Webhook은 다시 복구할 수 없으므로 신중하게 삭제해주세요.

❓

Webhook 상태가 자동으로 비활성화 되었습니다. 어떻게 해야 하나요?

2025년 5월 20일부로 Nodit의 플랜 정책이 일부 변경되어, 이제 Starter 플랜 사용자의 경우 생성한 Webhook이 최대 9일간만 활성화 상태로 유지됩니다. Starter 플랜 계정의 Webhook은 생성 또는 재활성화 후 9일이 지나면 UTC 00:00:00에 자동으로 비활성화 되며, 비활성화 2일 전에 안내 메일이 Nodit 계정 이메일로 발송됩니다. 비활성화된 Webhook은 콘솔의 Webhook 메뉴나 API를 통해 직접 재활성화할 수 있으며, 재활성화 시 다시 최대 9일간 사용 가능합니다.

Webhook을 지속적으로 사용하려면, 정기적으로 상태를 확인하여 필요시 직접 재활성화하시거나, 더 긴 사용을 원하실 경우 플랜 업그레이드를 권장드립니다.

API를 활용한 Webhook 생성 및 관리

어플리케이션의 구현에 따라 실시간으로 Webhook을 생성하고 삭제해야 하는 경우, API를 활용한 관리가 가능합니다. Webhook API Reference를 참고하여 API를 호출하고 Webhook이 정상적으로 생성되었는지 확인해보세요.