웹훅

API 폴링은 수신 시스템이 고정된 간격(1분마다, 5분마다)으로 소스 시스템에 '변경된 사항이 있나요?'라고 반복적으로 묻는 방식입니다. 이는 비효율적입니다. 대부분의 폴링 요청은 '변경 없음'을 반환하여 API 할당량을 소모하고 지연 시간(최대 지연 시간은 폴링 간격과 동일)을 발생시킵니다. 웹훅은 모델을 역전시킵니다. 이벤트가 발생하는 즉시 소스 시스템이 수신자에게 알림으로써 낭비되는 API 호출 없이 거의 제로에 가까운 지연 시간을 달성합니다. 한계는 신뢰성입니다. 웹훅은 기본적으로 '발사 후 망각' 방식이므로, 수신 시스템이 다운되면 이벤트가 손실됩니다. 잘 설계된 웹훅 시스템은 지수 백오프(점점 늘어나는 간격으로 여러 번 전송 시도)를 통한 재시도 로직과 전송 로그(제품 UI에서 고객이 엔드포인트가 각 이벤트를 수신했는지 확인하고 실패를 조사할 수 있도록 표시)를 추가합니다.

웹훅 실패는 통합의 양측에 걸쳐 발생하기 때문에 가장 복잡한 통합 지원 티켓 중 하나입니다. 일반적인 시나리오: (1) 엔드포인트가 이벤트를 수신하지 못함 — 엔드포인트 URL이 공개적으로 접근 가능한지(localhost가 아님), 서버가 테스트 이벤트를 수락했는지, 이벤트 유형이 구독되었는지 확인합니다. (2) HTTP 200 응답이 반환되지 않음 — 수신 서버는 타임아웃 시간(일반적으로 10~30초) 내에 HTTP 200 상태를 반환해야 합니다. 시간이 더 오래 걸리면 서버가 결국 이벤트를 처리했더라도 웹훅 플랫폼은 전송 실패로 표시합니다. (3) 중복 이벤트 — 잘 설계된 웹훅 소비자는 이벤트의 고유 ID를 사용하여 중복을 감지하고 무시함으로써 멱등성(동일한 이벤트를 두 번 처리해도 한 번 처리한 것과 동일한 결과 생성)을 가져야 합니다. (4) 서명 확인 실패 — 대부분의 SaaS API는 비밀 키를 사용하여 HMAC-SHA256으로 웹훅 페이로드를 서명합니다. 고객 코드는 스푸핑된 웹훅 공격을 방지하기 위해 수신된 모든 이벤트에서 이 서명을 확인해야 합니다.

Product Ops는 엔지니어링 팀과 협력하여 지원 부담을 최소화하고 개발자 만족도를 극대화하는 웹훅 기능을 설계합니다. 모범 사례: 이벤트 유형 범위(제품의 모든 의미 있는 상태 변경에는 해당 웹훅 이벤트가 있어야 함); 이벤트 페이로드 설계(페이로드는 후속 API 호출 없이 이벤트에 따라 조치하는 데 필요한 모든 데이터를 포함해야 함 — 후속 GET 요청이 필요한 ID만 포함하는 대신 전체 객체 상태를 포함); 전송 로그 UI(개발자가 모든 발생한 이벤트, 전송 상태, 서버의 HTTP 응답, 수동 재시도를 위한 '재전송' 버튼을 볼 수 있는 제품 대시보드의 검색 가능한 이벤트 로그); 서명 확인(모든 페이로드를 HMAC-SHA256으로 서명하고 확인 프로세스를 명확하게 문서화); 그리고 버전 관리된 페이로드(이벤트 스키마가 변경되어야 할 때, 페이로드에 버전을 지정하고 전환 기간 동안 두 버전을 동시에 지원 — 사전 통지 없이 웹훅 페이로드에 호환되지 않는 변경을 절대 하지 않음).