Support Hub/API & Integrations/웹훅 vs 폴링: 실시간 생체 데이터를 서버에 전달하는 올바른 방법
Translated from the English article and reviewed by a person. Read the English original
Developer

웹훅 vs 폴링: 실시간 생체 데이터를 서버에 전달하는 올바른 방법

웹훅 vs 폴링: 실시간 생체 데이터를 서버에 전달하는 올바른 방법

모든 생체 연동은 한 가지 기본 질문에 답해야 합니다. 출입구에서의 스캔이 어떻게 시스템의 기록이 되는가? 방법은 두 가지입니다. 서버가 장치에 새로운 일이 있었는지 계속 묻는 방식이 폴링입니다. 또는 시스템이 일이 발생한 순간 서버에 알려 주는 방식이 웹훅입니다. 생체 출결 및 출입 데이터의 경우, 웹훅과 폴링 중 무엇을 선택하느냐에 따라 데이터의 최신성, 장치와 네트워크에 가해지는 부하, 기록의 신뢰성이 달라집니다. 이 가이드에서는 두 방식을 쉽게 설명하고, 생체 데이터에 웹훅이 더 나은 기본값인 이유를 보여 주며, 안정적인 웹훅 수신기를 구축하는 방법을 다루고, 폴링이 여전히 유용한 경우를 설명합니다.

01 · 풀 vs 푸시

데이터가 전달되는 두 가지 방식

중요한 택배를 기다리고 있다고 상상해 보세요. 5분마다 현관까지 걸어 나가 택배가 도착했는지 확인할 수 있습니다. 또는 초인종이 울리기를 기다릴 수도 있습니다. 두 방법 모두 택배를 받게 해 줍니다. 하지만 첫 번째 방법은 많은 걸음을 낭비하고도 최대 5분 늦게 알게 됩니다. 두 번째 방법은 택배가 도착하는 순간 알려 줍니다.

이것이 폴링과 웹훅의 차이입니다.

폴링: 서버가 계속 묻는 방식

서버

질문: 마지막 이후 새로운 스캔이 있나요?

→

장치 또는 시스템

응답: 새로운 내용 없음

→

대기

폴링 간격만큼 대기

→

반복

하루 종일 계속해서 다시 묻기

웹훅: 시스템이 서버에 알려 주는 방식

직원 스캔

인증된 지문, 얼굴 또는 카드 스캔

→

게이트웨이

이벤트를 웹훅 URL로 즉시 전송

→

서버

이벤트를 수신하고 완료 응답을 보냄

→

완료

대기나 불필요한 요청 없음

폴링 웹훅
대화를 시작하는 주체 서버 데이터를 보유한 시스템
데이터 수신 시점 다음 폴링 시점에 수신되며, 최대 한 번의 간격만큼 늦어짐 스캔 직후 즉시
변경이 없을 때의 요청 지속적으로 발생하며, 대부분 빈 응답 없음
장치 및 네트워크 부하 활동 여부와 관계없이 지속적 전송할 데이터가 있을 때만
사용자 측 복잡성 이미 가져온 데이터 추적 이벤트 수신 및 확인 응답

02 · 숨은 비용

폴링이 생체 데이터에 어려움을 겪는 이유

폴링은 천천히 변하는 데이터나 지연이 중요하지 않은 데이터에 적합합니다. 생체 출결 및 출입 데이터는 정반대입니다. 근무 시작과 종료 시점에 집중적으로 발생하고, 그 외 시간에는 대부분 조용하며, 종종 즉시 필요합니다.

지연이 구조에 내재되어 있음

폴링에서는 최악의 지연이 항상 폴링 간격과 같습니다. 폴링 직후 1초 뒤에 발생한 스캔은 서버가 확인하기까지 전체 간격을 기다려야 합니다.

폴링 간격 시스템이 인지하기까지의 최악의 지연 적합한 용도
24시간마다 최대 하루 월간 급여 정산에만 적합
1시간마다 최대 60분 일일 보고서
5분마다 최대 5분 대부분의 대시보드(알림용 제외)
1분마다 최대 60초 거의 실시간에 가깝지만 요청 비용이 높음
웹훅 폴링 지연 없음 실시간 대시보드, 알림 및 자동화

대부분의 요청이 낭비됨

실시간에 가깝게 받으려면 폴링 빈도를 높여야 합니다. 하지만 이러한 요청 대부분은 아무것도 반환하지 않습니다. 장치 한 대를 1분마다 폴링하면 장치당 하루 1,440회의 요청이 발생합니다. 장치가 50대라면 하루 72,000회의 요청이며, 대부분은 “새로운 내용 없음”이라는 답을 얻기 위한 질문입니다. 이러한 요청 하나하나가 네트워크 용량과 장치의 처리 시간을 사용합니다.

추적 관리가 불안정해짐

폴링 연동은 이미 가져온 데이터를 기억해야 하며, 보통 마지막으로 확인한 레코드의 시간이나 위치를 저장하여 이를 처리합니다. 재시작, 서버와 장치 간의 시계 차이, 장치가 오프라인인 동안 저장된 레코드 등으로 이 기준점이 잘못되면, 연동은 스캔을 누락하거나 두 번 가져오게 됩니다. 이러한 문제는 눈에 잘 띄지 않으며, 종종 급여 분쟁이 발생했을 때에야 드러납니다.

사이트가 늘어날수록 더 어려워짐

장치가 한 대라면 폴링은 관리할 만합니다. 하지만 여러 사이트와 브랜드에 걸쳐 수십 대의 장치가 있고, 각각 고유한 연결, 고유한 간격, 고유한 마지막 조회 기준점을 가지고 있다면, 폴링은 그 자체로 별도의 일정 관리 및 모니터링 작업이 됩니다.

폴링은 몇 안 되는 중요한 순간을 포착하기 위해 하루에도 수천 번 같은 질문을 합니다. 웹훅은 실제로 무언가 발생했을 때만 신호를 보냅니다.

03 · Cams를 이용한 푸시 전달

생체 웹훅의 작동 방식

Cams Biometrics Gateway에서 웹훅 전달은 Callback API라고 합니다. 서버의 URL을 Gateway에 제공하면, 검증된 모든 스캔이 발생하는 즉시 그 URL로 전송됩니다. Native Push를 사용하는 장치의 콜백 이벤트는 지연 없이 전달됩니다.

서버가 수신하는 데이터

Callback API, Gateway가 웹훅 URL로 보내는 요청

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}
필드 서버에 전달하는 정보
OperationID 이 이벤트의 고유 참조 값
LabelName 장치가 할당된 사이트 또는 출입문의 이름
SerialNumber 스캔을 기록한 특정 장치
Type 출근인지 퇴근인지 여부
InputType 본인 확인 방법: 지문, 얼굴, 카드, PIN 등
UserId 스캔한 사람, HR 시스템의 ID와 일치
LogTime 장치에서 스캔이 발생한 시간(시간대 오프셋 포함)
AuthToken 서버가 요청이 정상임을 확인하는 데 사용하는 토큰
Time 메시지 자체의 타임스탬프(GMT 기준)

서버가 반드시 반환해야 하는 응답

서버가 이벤트를 수신하면 짧은 확인 응답을 보냅니다. 이를 통해 Gateway는 이벤트가 안전하게 도착했음을 알 수 있습니다.

Callback API, 웹훅이 반환해야 하는 응답

{ "status": "done" }

장치가 직접 할 수 없어도 푸시

모든 장치가 스스로 데이터를 푸시할 수 있는 것은 아닙니다. 일부 구형 또는 미인증 장치는 출결 데이터를 로컬 데이터베이스나 파일에만 저장합니다. Cams Hybrid Push를 사용하면 Gateway가 해당 데이터베이스에서 읽거나(DB Pull) 파일을 감시하여(File Processing) 새로운 출결 레코드를 여전히 Callback URL로 전달할 수 있습니다. 기반 장치가 일반적으로 폴링을 필요로 하더라도, 서버는 어떤 경우에든 푸시 방식으로 전달을 받게 됩니다.

04 · 모범 사례

안정적인 웹훅 수신기 구축하기

웹훅 수신기는 구축하기 간단하지만, 몇 가지 사례를 따르면 테스트에서만 작동하는 수신기와 수년간 매일 작동하는 수신기의 차이가 생깁니다.

사례 실행 방법 중요한 이유
먼저 확인 응답 보내기 이벤트를 수신하는 즉시 done 상태로 응답한 뒤, 이후에 느린 작업을 처리하세요 하위 시스템이 느리더라도 Gateway의 요청 시간을 짧게 유지합니다
작업을 큐에 넣기 수신한 각 이벤트를 큐나 테이블에 저장하고 별도로 처리하세요 근무 시작 시점의 집중 트래픽을 이벤트 손실 없이 처리합니다
AuthToken 검증 데이터를 신뢰하기 전에 모든 요청의 토큰을 확인하세요 다른 사람이 URL로 가짜 출결 데이터를 보내는 것을 막습니다
HTTPS 사용 웹훅은 HTTPS로만 노출하고, Gateway에서 선택적으로 AES-256 암호화를 적용하세요 출결 데이터는 개인 정보이므로 전송 중에도 보호되어야 합니다
멱등성 확보 OperationID를 사용하여 이미 처리한 이벤트를 감지하고 무시하세요 반복 전송된 이벤트가 중복 출결 기록이 되지 않습니다
출결은 LogTime 기준으로 서버가 이벤트를 수신한 시간이 아니라 LogTime을 사용하여 출결을 기록하세요 장애 중 저장된 이벤트는 늦게 도착하지만 실제 스캔 시간을 그대로 유지합니다
LogTime으로 정렬 근무 시간을 계산하기 전에 LogTime 순으로 이벤트를 정렬하세요 연결이 끊긴 후 버퍼링된 이벤트는 순서가 뒤바뀌어 도착할 수 있습니다
모든 내용 기록 수신한 모든 이벤트와 보낸 모든 응답의 기록을 보관하세요 문제 해결과 감사를 간편하게 합니다

평균이 아닌 폭주를 기준으로 계획하기

직원 300명이 있는 사이트는 하루의 대부분 거의 이벤트가 없다가, 교대 시간에 10분 동안 300개의 이벤트가 발생할 수 있습니다. 수신기는 이 최고치를 기준으로 설계하세요. 빠르게 확인 응답을 보내고 작업을 큐에 넣는 것이 이를 처리하는 가장 간단한 방법입니다.

웹훅을 배치할 수 있는 위치

웹훅에는 Gateway가 접근할 수 있는 공개 HTTPS 주소가 필요합니다. 이는 자체 애플리케이션의 엔드포인트, 작은 클라우드 함수, 또는 n8n이나 Make 같은 자동화 도구의 인커밍 웹훅일 수 있습니다. 장치 자체에는 공인 IP가 필요하지 않습니다. 방화벽 뒤에 있는 사이트는 아웃바운드 연결로 작동하는 Hybrid Connector를 통해 Gateway에 연결할 수 있습니다.

다음 단계는 시스템이 결정합니다

Gateway는 검증된 이벤트를 전달하고 사용자의 확인 응답을 기다립니다. 그 이후에 HRMS 기록, 대시보드 업데이트, 지각 알림 발송, 워크플로 시작 등 무슨 일이 일어날지는 사용자의 소프트웨어와 규칙에 따라 결정됩니다.

05 · 두 방식 함께 사용하기

폴링이 여전히 유용한 경우

생체 데이터의 실시간 수신에는 웹훅을 기본으로 사용해야 합니다. 하지만 요청 시 데이터를 가져오는 방식에도 유용하고 구체적인 역할이 있습니다. 가장 효과적인 연동은 실시간 전달에는 웹훅을, 점검과 복구에는 필요할 때의 가져오기를 함께 사용합니다.

상황 최적의 방식 이유
실시간 출결, 대시보드, 알림 웹훅(Callback API) 스캔이 발생하는 순간 데이터가 도착함
서버가 일정 기간 오프라인이었음 필요 시 로그 가져오기 누락된 구간을 채우고 아무것도 빠지지 않았는지 확인
매일 밤 또는 주간 대사 일정에 따라 로그 가져오기 웹훅으로 전달된 데이터와 비교하여 안전망으로 활용
새 연동 설정 과거 로그를 한 번 가져오기 웹훅이 시작되기 전에 기존 이력을 가져오기
특정 기간 감사 해당 기간의 로그 가져오기 검토를 위한 완전한 기록 생성

이러한 작업을 위해 Cams RESTful API에는 장치에서 로그를 불러오는 작업이 포함되어 있습니다. 필요할 때 의도적으로 사용하면, 로그 가져오기는 웹훅과 경쟁하기보다 웹훅을 보완합니다. 차이는 목적에 있습니다. 이유가 있을 때 가져오는 것이지, 혹시 모르니 매분 묻는 것이 아닙니다.

자주 묻는 질문

생체 데이터에서 폴링이 웹훅보다 나은 경우가 있나요?

시스템이 공개 엔드포인트를 전혀 노출할 수 없는 경우나 일회성 과거 데이터 가져오기의 경우에는 폴링이 더 간단할 수 있습니다. 지속적인 출결 및 출입 데이터의 경우, 웹훅이 더 빠르고, 장치와 네트워크에 부담이 적으며, 여러 사이트에 걸쳐 확장하기도 더 쉽습니다.

웹훅 서버가 다운되면 스캔 데이터는 어떻게 되나요?

웹훅 서버가 다운되면 출결 데이터는 Cams 큐에 저장됩니다. 서버가 다시 온라인 상태가 되면 큐에 있던 레코드가 자동으로 서버에 푸시됩니다. 큐는 3시간마다 자동으로 재시작되며, Cams Portal에서 언제든지 수동으로 재시작할 수도 있습니다. 이를 통해 일시적인 서버 중단으로 인해 출결 기록이 손실되지 않습니다.

웹훅이 작동하려면 생체 장치에 공인 IP가 필요한가요?

아니요. 웹훅 URL은 Gateway에서 접근할 수 있어야 하지만, 장치는 그럴 필요가 없습니다. 공인 IP가 없는 사이트는 아웃바운드 연결을 사용하는 Hybrid Connector를 통해 연결할 수 있습니다.

n8n, Make 또는 Zapier에서 웹훅을 받을 수 있나요?

예. 인커밍 웹훅을 받을 수 있는 도구라면 모두 Cams Callback 이벤트를 받을 수 있습니다. n8n과 Make는 필요한 done 확인 응답을 직접 반환할 수도 있습니다. Zapier는 그 응답을 보내기 위해 앞단에 작은 중계 서비스가 필요할 수 있습니다.

페이로드에서 LogTime과 Time이 다른 이유는 무엇인가요?

LogTime은 사람이 실제로 스캔한 시간이며, 장치의 시간대 오프셋과 함께 기록됩니다. Time은 메시지 자체의 타임스탬프이며 GMT 기준입니다. 장치가 오프라인이었다면 메시지는 스캔 시간보다 훨씬 늦게 전송될 수 있습니다. 출결에는 항상 LogTime을 사용하세요.

결론: 초인종이 울리게 하세요

폴링은 생체 장치를 요청할 때만 읽을 수 있었고 출결 데이터가 실시간일 것이라고 아무도 기대하지 않던 시절에는 합리적이었습니다. 오늘날 HR 대시보드, 급여 시스템, 자동화 도구, AI 어시스턴트는 데이터가 생성되는 순간 가장 잘 작동합니다. 장치에 하루 수천 번 같은 질문을 하는 것은 그 지점에 도달하는 느리고 낭비적인 방법입니다.

웹훅은 검증된 모든 스캔을 시스템이 즉시 받는 이벤트로 바꿔 주며, 불필요한 요청도 없고 이미 가져온 데이터를 불안정하게 추적할 필요도 없습니다. 요청 시 로그 가져오기는 빈틈을 메우고 완전성을 확인하는 가장 적합한 용도로 유지하고, 나머지는 웹훅이 처리하도록 하세요.

Cams Biometrics Gateway는 푸시 전달을 중심으로 설계되었습니다. Callback API는 15개 이상의 브랜드 장치에서 검증된 모든 스캔을 일관된 JSON 형식으로 실시간 웹훅에 전송합니다. Hybrid Push 모드는 스스로 푸시할 수 없는 장치에서도 푸시 이벤트를 전달하며, RESTful API는 대사를 위한 로그 불러오기와 같은 요청 시 작업을 제공합니다. 모든 통신은 인증 토큰 검증과 선택적 AES-256 암호화를 적용한 HTTP/HTTPS로 이루어집니다. CamsBiometrics.com에서 플랫폼을 살펴보고, developer.camsbiometrics.com에서 전체 Callback API 문서를 읽어보세요.

Was this article helpful?