웹훅

웹훅이란?

웹훅을 붙이면 일의 주어가 바뀝니다. 폴링 방식에서는 우리 서버가 1분마다 결제사 API를 두드리며 '새 결제 있나요'를 묻습니다. 하루 1,440번을 물어도 실제로 건지는 건 수십 건뿐이고 나머지는 전부 빈 조회입니다. 웹훅으로 돌리면 그 헛질문이 사라지면서 사건 발생부터 처리까지가 분 단위에서 초 단위로 줄고, API 호출 한도를 갉아먹던 빈 조회가 통째로 없어져 서버 비용과 장애 지점도 같이 줄어듭니다.

붙이기 전에 챙길 항목은 서명 검증·응답 속도·재시도·멱등 처리 네 가지입니다. 대부분의 서비스는 요청 헤더에 HMAC 서명을 실어 보내니 시크릿 키로 대조해 위조 요청을 걸러야 하고, 받는 쪽은 보통 3~5초 안에 200 OK를 돌려줘야 합니다. 재고 차감이나 메일 발송처럼 무거운 작업은 큐에 넣고 응답부터 내보내는 게 정석입니다. 실패하면 제공사가 몇 분에서 몇 시간 간격으로 수차례 다시 쏘기 때문에, 같은 이벤트 ID가 두 번 와도 주문은 한 번만 잡히도록 막아두어야 합니다.

비슷해 보이는 도구와 선을 그어두면 설계가 쉬워집니다. 일반 API는 우리가 필요할 때 꺼내 쓰는 창구지만, 웹훅은 상대가 한 번 던지고 마는 통보라 받는 순간 처리하지 못하면 그대로 흘러갑니다. 화면을 실시간으로 갱신하는 게 목적이면 SSE나 웹소켓이 맞고, 하루 수십만 건을 순서대로 쌓아야 하면 카프카·SQS 같은 메시지 큐가 맞습니다. 웹훅은 '하루 수천 건 수준의 사건 전달'에 가장 잘 맞는 중간 도구입니다.

현장에서 제일 자주 깨지는 건 '웹훅은 한 번만, 보낸 순서대로 온다'는 믿음입니다. 재전송과 네트워크 사정 탓에 같은 결제 완료가 두 번 들어와 주문이 두 건 생기고 재고가 두 번 빠지는 사고가 실제로 납니다. 사내 방화벽 뒤에 수신 서버를 둔 탓에 개발 환경에서는 잘 오던 알림이 운영에서는 한 건도 안 들어오는 경우도 흔합니다. 웹훅은 '가끔 유실되는 통보'로 전제하고, 돈이 걸린 이벤트는 하루 한 번 원장 대사(재조회) 배치를 함께 돌려야 밤사이 빠진 건을 잡아냅니다.