웹훅 URL을 아는 사람이라면 누구나 요청을 보낼 수 있습니다. 따라서 발신처를 주장하는 헤더만 믿어서는 안 됩니다. 서명 검증과 시간 제한, 중복 이벤트 처리를 함께 설계해야 정상 알림은 받으면서 위조·재생 요청을 막을 수 있습니다.
원본 바이트로 서명을 검증한다
JSON을 파싱한 뒤 다시 문자열로 만들면 공백이나 필드 순서가 달라질 수 있습니다. 제공자의 방식에 따라 요청 원본 바이트와 서명 헤더, 비밀키로 검증합니다. 검증이 끝나기 전에는 결제나 주문 상태를 바꾸지 않습니다.
시간 정보로 오래된 재생을 제한한다
공격자가 과거의 유효한 요청을 복사해 다시 보낼 수 있습니다. 서명에 포함된 타임스탬프와 허용 오차를 확인하고 서버 시계를 동기화합니다. 시간이 맞지 않는 요청을 무조건 수용하거나 오차를 지나치게 넓히면 방어 효과가 줄어듭니다.
유효한 재전송은 멱등하게 처리한다
제공자는 응답 실패 시 정상 이벤트를 다시 보낼 수 있습니다. 서명이 맞아도 이벤트 ID로 이미 처리했는지 확인하고 같은 업무 효과를 두 번 만들지 않습니다. 서명 검증은 진위 확인이고 중복 처리는 별개의 문제입니다.
비밀키의 수명주기를 관리한다
테스트와 운영 키를 분리하고 접근 권한을 줄입니다. 키 교체 기간에는 구키와 신키를 어떻게 처리할지 정하고, 잘못된 키가 로그에 남지 않도록 합니다. 검증 실패를 분석할 때 원본 전체를 무심코 저장하지 않습니다.
장애와 공격을 구분해 관찰한다
서명 오류가 늘면 위조 시도일 수도 있고 배포 과정의 본문 변경 문제일 수도 있습니다. 검증 실패 사유, 시계 차이, 중복률을 분리해 봅니다. 실제 이벤트를 놓치지 않도록 실패 알림과 재전송 복구 경로를 준비합니다.
현장에 적용할 때의 순서
- 원본 바이트·서명 검증
- 시각 허용 범위 확인
- 이벤트 ID로 멱등 처리
주의할 실패: 서명만 맞으면 무조건 재실행
관찰할 지표: 검증 실패·중복·시계 차이
적용 전 체크리스트
- 파싱 전 원본 요청으로 서명을 검증하는가
- 타임스탬프 허용 오차와 서버 시계를 관리하는가
- 유효한 중복 이벤트도 한 번만 처리하는가
참고 자료
Stripe Webhooks documentation. 서명 검증·타임스탬프·재시도에 관한 제공자 문서를 참고했습니다. 실제 헤더와 서명 방식은 웹훅 제공자마다 다릅니다.
이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.
#웹훅보안 #서명검증 #재생공격 #멱등성 #API보안 #이벤트처리 #결제연동 #백엔드 #비밀키관리 #재시도
