결제 웹훅 중복 수신 막고 정산 추적 로그 정비

웹훅 개선하면서 깨달은 것

결제대행사 쪽에서 들어오는 웹훅이 가끔 누락되거나 중복으로 찍히는 이슈가 있었음. 처음엔 "재시도 정책이려니" 하고 넘겼는데, 정산 데이터 검수하다가 같은 거래에 대해 콜백이 3번 들어온 케이스를 발견했음. 더는 못 미루겠다 싶어서 손댐.

무엇을 바꿨나

핵심은 두 가지. 웹훅 수신부 자체의 멱등성 보장과 로그를 사후 추적 가능한 형태로 남기는 것.

• 동일 거래키로 중복 수신될 때 첫 건만 처리하고 이후는 200으로 받아치기 (재시도 폭주 방지)
• 요청 본문 raw 그대로 별도 저장소에 적재 → 파싱 실패해도 원본은 남음
• 응답 코드/소요 시간/처리 결과를 한 줄 로그로 통합

기존엔 컨트롤러마다 로그 포맷이 다 달라서, 사고 났을 때 grep 으로 한 번에 추리는 게 불가능했음. 포맷을 통일하니 운영팀이 직접 검색해서 원인 짚는 빈도가 늘었음.

로그 정책 정리

라벨링 한 줄 바꾼 게 의외로 컸음. 외부 요청 ID 를 같이 박아두니 결제대행사 측에 문의할 때 "그쪽 시스템에서 이 ID로 보낸 거 맞냐" 바로 물어볼 수 있게 됨. 이전엔 우리 거래키만 있어서 매번 매핑 떠야 했음.

[WEBHOOK] provider=A txKey=xxx extId=yyy status=OK elapsed=42ms
[WEBHOOK] provider=A txKey=xxx extId=yyy status=DUP_SKIP

수동 발급 화면도 같이 손봄

운영 중에 콜백을 못 받아서 수동으로 처리해야 하는 건들이 종종 있음. 이 화면도 같이 정비했는데, 기존엔 폼에 거래키 하나만 넣고 "처리" 누르면 끝이라 누가 무엇을 왜 발급했는지 흔적이 없었음. 발급 사유와 작업자를 강제 입력으로 바꿈.

• 사유 미기재면 발급 불가
• 작업자 식별자 자동 기록
• 발급 결과는 웹훅 처리 로그와 동일한 포맷으로 적재 → 자동/수동 구분 없이 한 줄로 추적

회고

처음엔 "콜백 한 번 더 받는 게 뭐 그리 큰일이라고" 싶었는데, 정산 사이클이 돌아가는 환경에서 중복 처리 한 건이 며칠 뒤에 클레임으로 돌아옴. 멱등성은 만들 때 귀찮아도 안 만들면 더 귀찮아진다는 걸 또 배움. 그리고 로그는 "찍는 것"보다 "찾을 수 있게 찍는 것"이 본질이라는 것도.

다음