웹훅, 시작은 쉬운데 프로덕션에선 왜 지옥일까 — 중복·순서·보안까지 살아남는 설계법

결제는 분명히 됐는데 주문 상태가 안 바뀌어요. 로그를 뒤져보니 결제사가 보낸 웹훅이 그 시각에 안 왔거나, 두 번 왔거나, 순서가 뒤집혀서 왔더라고요. 웹훅을 프로덕션에서 운영해본 분이라면 한 번쯤 겪어봤을 장면인데요. 웹훅의 겉보기 단순함과 실제 운영의 어려움 사이에 놓인 깊은 골짜기를 다룬 글이 올라와서, 그 내용을 바탕으로 웹훅에서 살아남는 법을 정리해봤어요.

웹훅이 뭐냐면

먼저 개념부터요. 웹훅은 어떤 서비스에서 이벤트가 발생했을 때, 그 서비스가 내가 등록해둔 URL로 HTTP POST 요청을 보내주는 방식이에요. 내가 계속 '새 소식 있어요?' 하고 물어보는 폴링(polling)과 반대로, 상대방이 '일 생기면 문자 줄게' 하는 구조죠. 결제 완료 알림, GitHub 푸시 이벤트, 메신저 봇까지 어디에나 쓰여요. 엔드포인트 하나 만들고 URL 등록하면 끝이니까 시작은 정말 쉬워요. 문제는 그다음부터예요.

함정 1: 재시도와 중복 — 같은 이벤트가 두 번 온다

내 서버가 배포 중이거나 잠깐 죽어 있을 때 웹훅이 오면 어떻게 될까요? 제대로 된 발신 측이라면 실패를 감지하고 재시도해요. 그런데 재시도는 필연적으로 중복을 낳아요. 내 서버가 처리는 다 했는데 응답만 늦게 보낸 경우, 발신 측은 실패로 간주하고 같은 이벤트를 또 보내거든요. 이걸 '최소 한 번 전달(at-least-once delivery)'이라고 하는데, '정확히 한 번' 전달은 분산 시스템에서 사실상 보장이 불가능해서 대부분 이 방식을 써요.

그래서 수신 측의 필수 덕목이 멱등성(idempotency)이에요. 이게 뭐냐면, 같은 요청을 몇 번 처리해도 결과가 한 번 처리한 것과 같도록 만드는 성질이에요. 실전에서는 웹훅에 담긴 이벤트 ID를 DB에 유니크 제약으로 저장하고, 이미 있는 ID면 조용히 무시하는 식으로 구현해요. '결제 완료 웹훅 두 번 수신 → 포인트 두 번 적립' 같은 사고를 막는 최소한의 안전장치죠.

함정 2: 순서는 보장되지 않는다

더 미묘한 함정은 순서예요. '주문 생성' 웹훅보다 '주문 취소' 웹훅이 먼저 도착할 수 있어요. 재시도, 네트워크 지연, 발신 측의 병렬 처리가 겹치면 순서는 얼마든지 뒤집혀요. 이벤트가 도착한 순서대로 상태를 덮어쓰는 코드는 언젠가 반드시 틀린 상태를 만들어요.

가장 견고한 해법은 웹훅을 '진실'이 아니라 '알림'으로 취급하는 거예요. 웹훅이 오면 페이로드 내용을 그대로 믿고 반영하는 대신, '뭔가 바뀌었구나' 하는 신호로만 쓰고 발신 측 API를 호출해서 최신 상태를 새로 조회하는 거죠. Stripe 같은 서비스들이 권장하는 패턴이기도 해요. 최신 상태를 다시 읽어오면 이벤트가 뒤집혀 도착해도 결과는 항상 올바르거든요. API 호출을 늘리고 싶지 않다면 이벤트에 버전 번호나 타임스탬프를 실어서, 이미 반영한 것보다 오래된 이벤트는 버리는 방법도 있어요.

함정 3: 그 요청, 진짜 걔가 보낸 거 맞아요?

웹훅 엔드포인트는 결국 인터넷에 열린 URL이에요. 아무나 그럴듯한 JSON을 만들어 POST할 수 있다는 뜻이죠. '결제 완료' 웹훅을 위조해서 보내는 공격을 막으려면 서명 검증이 필요해요. 보통 발신 측이 미리 공유한 시크릿 키로 페이로드의 HMAC 서명(내용이 조금이라도 바뀌면 값이 달라지는 암호학적 지문)을 만들어 헤더에 실어 보내고, 수신 측이 같은 계산을 해서 값이 일치하는지 확인하는 방식이에요. 여기에 타임스탬프를 함께 서명해서 오래된 요청을 거부하면, 가로챈 요청을 나중에 재전송하는 리플레이 공격까지 막을 수 있어요.

함정 4: 핸들러 안에서 일하지 마세요

웹훅 핸들러 안에서 DB 갱신, 이메일 발송, 외부 API 호출까지 다 하면 응답이 느려져요. 발신 측은 보통 몇 초 안에 응답이 없으면 실패로 보고 재시도하는데, 그러면 느린 처리 때문에 중복 요청이 쌓이면서 부하가 눈덩이처럼 커져요. 정석은 받자마자 큐에 넣고 즉시 200을 반환한 뒤, 실제 처리는 백그라운드 워커가 하는 거예요. 처리에 실패한 이벤트를 모아두는 데드레터 큐까지 두면 유실 걱정도 줄고요. 참고로 로컬 개발 환경은 외부에서 접근이 안 되니까, 개발 중에는 ngrok 같은 터널링 도구로 웹훅을 받아보는 게 일반적이에요.

업계 맥락

이런 어려움이 워낙 보편적이다 보니 Svix나 Hookdeck처럼 웹훅 수발신 인프라만 전문으로 하는 서비스도 자리를 잡았어요. Stripe와 GitHub의 웹훅 문서는 사실상 이 분야의 교과서고요. 규모가 커지면 웹훅 대신 Kafka 같은 이벤트 스트리밍으로 넘어가는 선택지도 있지만, 서로 다른 회사의 시스템을 잇는 용도로는 여전히 웹훅이 표준이에요.

마무리

정리하면 이래요. 웹훅은 시작이 쉬운 만큼 함정이 늦게 드러나는 기술이고, 멱등성·상태 재조회·서명 검증·비동기 처리 이 네 가지만 챙겨도 골짜기 대부분을 건널 수 있어요. 여러분이 웹훅 때문에 겪은 최악의 장애는 뭐였나요? 중복이었나요, 순서였나요?