장치 웹훅(Webhook) 설정하기
CLUe 포털에서 웹훅(Webhook)을 설정하면, 지정한 이벤트가 발생했을 때 장치가 사용자가 지정한 엔드포인트(외부 서버)로 실시간 이벤트를 전송합니다. 이 기능으로 다음과 같은 사용 사례를 구현할 수 있습니다.
-
근태 기록 시스템과의 연동
-
중복 얼굴 감지 이벤트 수신
이 외에도 시스템과의 다양한 실시간 이벤트 기반 연동에 활용할 수 있습니다.
지원 장치
| 장치 | 모델 | 지원 펌웨어 버전 |
|---|---|---|
| BioStation 3 | BS3-DB, BS3-APWB | bs3-all_v1.1.0_20250626 이상 |
다음 CLUe 지원 장치도 웹훅을 지원할 예정입니다.
- BioEntry W3, BioLite N2, X-Station 2, XPass 2
주요 장점
-
장치의 실시간 이벤트 알림을 외부 시스템으로 전송할 수 있습니다.
-
웹훅을 통해 외부 시스템과 손쉽게 연동할 수 있습니다.
-
인사 근태 연동, 보안 이벤트 모니터링 등의 사용 사례를 지원합니다.
웹훅 설정
-
CLUe 웹 포털에 로그인하세요.
-
웹훅을 설정할 장치가 할당된 공간으로 이동하세요.
-
화면 왼쪽 사이드바에서 출입장치를 클릭하세요.
-
장치 목록에서 웹훅을 설정할 장치를 선택하세요.
-
화면 상단의 웹훅 탭을 클릭하세요.
웹훅 탭이 표시되지 않으면, 장치의 CLUe 펌웨어 버전을 확인한 후 지원하는 펌웨어 버전 이상으로 업데이트하세요.
메서드
웹훅은 POST 메서드를 기본 사용합니다.
엔드포인트(URL) 설정
-
온라인 이벤트: 장치가 온라인 상태일 때 지정한 이벤트가 발생하면 실시간 웹훅 호출을 전송하는 엔드포인트입니다.
-
오프라인 이벤트: 장치가 오프라인 상태였다가 다시 온라인 상태로 전환되면, 그동안 발생한 이벤트를 목록 형태로 전송하는 엔드포인트입니다.
웹훅 필드 구성
장치에서 전송할 데이터를 정의하려면 웹훅 필드를 구성하세요.
-
자동 필드: 장치가 전송할 수 있는 데이터 집합의 유형을 나타냅니다.
-
nonString: Boolean, int와 같이 따옴표(
"")로 감싸지 않는 데이터 유형을 의미합니다.
필요한 데이터 필드를 선택한 후 미리보기 패널에서 웹훅 페이로드를 미리 확인할 수 있습니다.
추가로 고정된 값을 포함해야 하면 수동 필드로 추가할 수 있습니다. 이 값은 웹훅 페이로드와 함께 고정 값으로 전송됩니다.
테스트 호출 실행
설정을 완료하면 테스트 호출을 실행할 수 있습니다.
테스트 호출은 실제 장치가 아닌 브라우저에서 직접 설정된 엔드포인트로 전송되는 데이터의 구조와 형식을 확인할 수 있게 해줍니다.
참고 사항
서버가 아직 준비되지 않아도 인터넷에서 공개적으로 제공되는 웹훅 테스트 서비스를 사용해 웹훅 테스트를 진행할 수 있습니다. 예를 들어, Webhook.site를 사용해 웹훅 호출을 손쉽게 확인할 수 있습니다.
