웹훅
쉽게 풀면
택배가 도착하면 문자로 알려주는 서비스를 떠올려 보세요. 내가 계속 배송 조회 페이지를 새로고침하며 확인할 필요 없이, 택배가 도착하는 "사건"이 발생하는 순간 배송 회사가 알아서 내 번호로 문자를 보내줍니다. 웹훅도 같은 원리입니다.
어떤 시스템(A)이 "이런 일이 생기면 이 주소로 알려줘"라고 다른 시스템(B)에 자신의 콜백 주소를 미리 등록해두면, B는 해당 사건이 실제로 발생했을 때 그 주소로 데이터를 담아 자동으로 요청을 보냅니다.
그래서 A는 "혹시 무슨 일 생겼나?" 하고 계속 물어보는(폴링) 대신, 일이 생겼을 때만 알림을 받아 즉시 반응할 수 있습니다.
왜 중요한가
웹훅은 서버가 지속적으로 상태를 확인(폴링)하지 않고도 실시간에 가깝게 이벤트를 전달할 수 있게 해주기 때문에, 마이크로서비스 간 통신, 서드파티 서비스 연동, IoT 기기의 상태 알림 등 다양한 분야의 시스템 설계 논문에서 이벤트 기반 아키텍처의 핵심 구성 요소로 다루어집니다. 서버 자원을 절약하면서도 반응 속도를 높일 수 있다는 장점 때문에, 확장성과 효율성을 다루는 분산시스템 연구에서도 자주 등장합니다.
핵심 정리
- 웹훅은 사건이 일어난 시스템이 미리 등록된 URL로 HTTP 요청(보통 POST)을 보내 알려 주는 방식입니다. 받는 쪽은 서버를 열어 두고, 요청 본문(페이로드)에 담긴 사건 정보를 처리합니다. 푸시(push)형 통지의 웹 버전입니다.
- 일반적인 호출은 클라이언트가 먼저 묻는 요청-응답(풀, pull)입니다. 웹훅은 방향이 반대여서 ‘역방향 API’라고도 불리며, 변화를 계속 묻는 폴링(polling)을 대체합니다.
- 구성 요소는 ① 사건 종류(결제 완료, 코드 푸시 등) 구독, ② 수신 URL 등록, ③ 페이로드 형식(대개 JSON), ④ 서명이나 비밀 토큰 같은 진위 확인 수단입니다.
- 전달 보장은 일반적으로 적어도 한 번(at-least-once)입니다. 실패하면 송신 측이 재시도하므로 같은 사건이 중복해서 도착할 수 있고, 도착 순서도 보장되지 않는 경우가 많습니다. 그래서 수신 측은 같은 사건을 여러 번 받아도 결과가 같도록(멱등성) 사건 식별자로 중복을 걸러냅니다(Kleppmann, 2017이 분산 시스템의 전달 의미를 정리했습니다).
- 웹훅은 REST API처럼 자원을 다루는 설계 규칙이 아니라 통지 방식입니다. 서비스는 두 가지를 함께 제공하는 경우가 많고, API 앞단에서는 API 게이트웨이가 요청을 받아 인증·분배합니다.
예시로 보기
가상의 비교입니다. 하루 평균 20건의 사건이 생기는 서비스의 상태를 60초마다 폴링하면 하루 1,440번 요청하고, 그중 약 98.6%는 빈 응답입니다. 사건을 알아차리는 데 걸리는 지연은 평균 30초, 최대 60초입니다. 웹훅은 요청이 사건 수와 같은 20건이고, 지연은 네트워크 전달 시간 정도입니다. 대신 수신 서버가 항상 요청을 받을 수 있게 열려 있어야 하고, 위조된 요청과 중복 전송에 대비하는 설계 부담을 집니다.
자주 하는 오해
| 오해 | 바로잡기 |
|---|---|
| 웹훅은 REST API의 한 종류이다. | 웹훅은 사건을 알리는 방식이고, REST는 자원 중심 설계 규칙입니다. 서로 층위가 다릅니다. |
| 웹훅은 한 번만, 순서대로 온다. | 재시도로 중복이 생기고 순서가 바뀔 수 있으므로 멱등 처리가 필요합니다. |
| URL을 비밀로 하면 안전하다. | URL이 노출되면 누구나 위조 요청을 보낼 수 있습니다. 서명 검증 같은 진위 확인이 일반적입니다. |
| 웹훅이면 항상 실시간이다. | 송신 측의 큐, 재시도 정책, 수신 서버 처리 지연에 따라 늦어질 수 있습니다. |
논문에서는 이렇게 쓰입니다
실제 논문에서
이 용어를 직접 쓴 국내 논문 문장을 아직 수집하지 못했습니다. 수집되는 대로 출처와 함께 싣겠습니다.
예시 문장
아래는 용어의 쓰임을 보여 주려고 만든 예시로, 실제 논문에서 가져온 문장이 아닙니다.
이 문장은 결제가 끝나는 순간 그 사실을 다른 시스템에 즉시 전달하도록 설계했다는 뜻으로, 이벤트 기반 아키텍처나 시스템 통합 방식을 설명하는 논문에서 자주 쓰입니다.
소프트웨어 공학 분야에서는 코드 변경이라는 이벤트를 웹훅으로 감지하여 자동화된 빌드·배포 과정을 시작시키는 지속적 통합 환경을 구성하는 사례가 흔히 보고됩니다.
사물인터넷 분야에서는 센서의 이상 상황을 지속적으로 확인하는 대신, 이벤트가 발생했을 때만 웹훅으로 알림을 보내 자원 소모를 줄이고 반응 속도를 높이는 방식이 활용됩니다.
조금 더 깊게 보면
웹훅을 실제로 안전하게 운용하려면 수신 측이 요청의 출처를 검증하는 절차(예: 서명 검증, 비밀 토큰 확인)가 필요한데, 이는 누구나 알림 주소만 알면 위조된 요청을 보낼 수 있기 때문입니다.
또한 네트워크 문제로 알림이 유실되거나 중복 전송될 수 있어, 송신 측은 재시도(retry) 로직을, 수신 측은 동일한 이벤트를 여러 번 받아도 결과가 달라지지 않도록 하는 멱등성(idempotency) 처리를 갖추는 것이 일반적입니다.
최근에는 웹훅과 유사한 목적을 메시지 큐나 발행-구독 패턴으로 대체해 안정성과 순서 보장을 강화하는 아키텍처도 함께 논의됩니다.
주의할 점
웹훅은 클라이언트가 서버에 요청을 보내야만 응답을 받는 일반적인 REST API (자원 중심 API 설계) 호출과 방향이 반대입니다. 즉 요청을 보내는 주체가 우리 쪽이 아니라 사건이 발생한 시스템이라는 점에서, 수신 측은 예상치 못한 시점에 오는 요청을 안전하게 검증하고 처리할 준비가 되어 있어야 합니다. 알림이 순서대로 오거나 반드시 한 번만 온다는 보장이 없는 경우도 많아, 중복 처리나 순서 뒤바뀜에 대비한 설계가 필요합니다.
헷갈리기 쉬운 용어
시스템 사이에서 정보를 주고받는 방식은 누가 시작하느냐로 나뉩니다.
| 용어 | 누가 시작하나 | 한 줄 설명 |
|---|---|---|
| 웹훅 | 사건이 생긴 쪽 | 사건 시 등록된 URL로 HTTP 요청을 보내 알림 |
| 폴링 | 받는 쪽 | 주기적으로 ‘바뀐 게 있나’ 묻는 방식 |
| REST API | 요청하는 쪽 | 자원을 URL로 표현하고 정해진 HTTP 메서드로 주고받는 설계 규칙 |
| API 게이트웨이 | —(중간 관문) | 여러 서비스로 가는 요청을 한곳에서 받아 인증·분배 |
| 메시지 큐·발행-구독 | 브로커가 중계 | 송신자와 수신자를 분리해 안정성과 순서 보장을 강화하는 대안 |
참고 문헌
- Fielding, R. T. (2000). Architectural Styles and the Design of Network-based Software Architectures (Doctoral dissertation). University of California, Irvine.
- Hohpe, G., & Woolf, B. (2003). Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley.
- Kleppmann, M. (2017). Designing Data-Intensive Applications. O'Reilly Media.
- Richardson, C. (2018). Microservices Patterns. Manning Publications.
표의 기준값은 위 문헌에 근거한 관례이며, 분야·학술지마다 다른 기준을 쓸 수 있습니다.