3년 차 백엔드 개발자가 로컬 개발 환경에서 웹훅 유실과 중복 처리를 해결하는 방법
TuBrief 편집팀
2026년 8월 22일
0
컴퓨터/소프트웨어원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
분산 시스템에서 결제나 알림 연동을 맡아본 적 있다면 외부 서비스 응답 지연이나 네트워크 단절 때문에 데이터가 유실되거나 중복 전송되는 상황에 지쳐있을 것이다. 웹훅은 최소 한 번 전송을 보장하므로 수신 서버가 제대로 준비되어 있지 않으면 데이터 오염으로 이어진다. 운영 환경에 배포하기 전에 로컬 환경에서 장애 상황을 시뮬레이션하고 방어 로직을 구현하는 방법을 다룬다.
실제 장애 상황을 운영 배포 전에 검증하려면 로컬 환경에 카오스 테스트 파이프라인을 만들어야 한다. ngrok 터널링과 Docker 기반의 Toxiproxy를 조합하면 외부 제공업체의 타임아웃과 네트워크 단절을 재현할 수 있다. 이 환경을 구축하면 장애 원인 분석 및 대응에 소요되는 시간을 2시간 단축할 수 있다.
Toxiproxy를 활용해 네트워크 장애를 주입하는 절차는 이렇다. 첫째, Docker Compose로 백엔드 앱, Toxiproxy, ngrok을 연결하고 ngrok 공개 URL로 들어온 요청이 Toxiproxy 포트 8666을 거쳐 앱 8080으로 진입하도록 설정한다. 둘째, Toxiproxy 관리 API에 cURL 요청을 보내 25000밀리초의 응답 지연을 주입하여 Stripe 같은 외부 서비스의 타임아웃 조건을 유발한다. 셋째, reset_peer toxic을 적용해 소켓을 강제로 종료하고 커넥션 풀 복구 및 로그 포착 여부를 검증한다.
웹훅 재전송으로 인한 중복 트랜잭션은 결제 승인 과정에서 데이터 오염을 일으킨다. 메모리 캐시는 분산 서버 환경에서 레이스 조건을 막지 못하므로 부적절하다. 확실한 중복 차단을 위해 RDBMS의 트랜잭션과 유니크 제약 조건을 멱등성 게이트로 써야 한다.
데이터베이스 레벨에서 동시성 요청을 제어하는 구현 절차는 다음과 같다. 첫째, processed_webhooks 테이블을 만들고 페이로드 내부의 고유 이벤트 식별자에 UNIQUE 제약 조건을 부여한다. 둘째, FastAPI와 SQLAlchemy 환경에서 원자적 Insert 문을 사용하여 상태를 처리 중으로 기록하고 동시성 충돌 발생 시 IntegrityError를 캐치한다. 셋째, 유니크 제약 위반 시 기존 레코드의 상태를 조회하여 이미 처리된 요청이면 데이터 변조 없이 200 OK를 반환하여 외부 서비스의 재전송을 중단시킨다. 이 구조를 적용하면 중복 요청으로 인한 데이터 오염 사고를 방지한다.
웹훅 처리 중 외부 의존성 장애가 발생하면 재시도 횟수를 초과한 이벤트들이 생기고, 이를 데드 레터 큐에 격리한다. 실패 이벤트를 방치하면 데이터 불일치가 누적되므로 시스템이 정상화되었을 때 안전하게 재주입하는 배치 프로세스가 필요하다. 파이썬 기반의 수동 복구 스크립트를 구축하면 주당 3시간 소요되던 수동 SQL 복구 작업을 절약할 수 있다.
격리된 실패 이벤트를 재처리하는 배치 스크립트 구현 절차는 이렇다. 첫째, dlq_webhooks 테이블을 생성하여 원본 페이로드, 에러 메시지, 시도 횟수를 기록하고 is_resolved가 거짓인 데이터를 조회한다. 둘째, 재처리 시 네트워크 폭주를 막기 위해 지수 백오프와 지터 알고리즘을 적용하여 계산된 지연 시간만큼 대기한다. 셋째, 내부 엔드포인트로 HTTP 요청을 전송하고 성공 시 is_resolved를 참으로 업데이트하며, 실패 시 횟수를 증가시키되 최대 제한을 두어 무한 루프를 차단한다.
웹훅 시스템의 안정성을 유지하려면 수신 실패율과 데드 레터 큐 누적 건수를 실시간으로 추적하는 관측 가능성 체계가 필요하다. 일시적인 인프라 흔들림으로 인해 야간마다 온콜 엔지니어에게 알림이 울리는 피로도를 차단하려면 오류 성격에 따른 계층화된 알림 정책을 세워야 한다.
오탐지를 줄이고 실제 장애에만 대응하기 위한 모니터링 설정 절차는 다음과 같다. 첫째, 최근 10분간의 총 수신 건수 대비 HTTP 5xx 및 타임아웃 응답 건수를 바탕으로 웹훅 실패율을 산출한다. 둘째, 일시적 인프라 에러와 비즈니스 로직 에러를 대시보드 상에서 분리하여 시각화한다. 셋째, 실패율 15퍼센트 초과 및 데드 레터 큐 100건 초과 조건일 때만 PagerDuty 긴급 호출을 작동시키고, 단순 타임아웃은 야간 무음 처리하여 온콜 피로도를 낮춘다.