웹훅을 받기 전에 서명을 검증해야 하는 이유

웹훅 URL을 아는 사람은 누구나 비슷한 JSON을 보낼 수 있습니다. 수신 서버가 본문 내용만 보고 주문 완료나 결제 성공을 처리하면 위조 요청에 속을 수 있습니다. 발신자를 확인하는 서명 검증이 업무 처리보다 앞에 와야 합니다.

원시 본문으로 검증한다

서명은 보통 수신한 바이트와 비밀 키로 계산합니다. JSON을 파싱하고 다시 문자열로 만들면 공백이나 필드 순서가 달라져 검증이 실패할 수 있으므로 원시 요청 본문을 사용합니다. 일부 제공자는 서명 비밀 키를 엔드포인트별로 다르게 발급합니다. 테스트용 비밀 키로 운영 이벤트를 검증하거나 여러 엔드포인트의 키를 혼용하면 정상 요청을 거부하거나 보안 경계를 흐릴 수 있습니다.

발신 서비스의 공식 방식만 따른다

헤더 이름, 서명 알고리즘, 타임스탬프 허용 범위, 비밀 키 회전 방법은 제공자마다 다릅니다. 일반적인 HMAC 예제를 그대로 복사하지 말고 해당 제공자의 공식 SDK와 문서를 확인합니다.

재전송 공격을 막는다

서명이 유효해도 과거 요청을 다시 보내는 공격은 별도 문제입니다. 타임스탬프 허용 범위와 이벤트 ID 중복 처리 기록을 함께 적용해야 합니다.

실패 요청은 처리하지 않는다

서명 누락이나 불일치, 오래된 타임스탬프는 업무 큐로 보내지 않습니다. 로그에는 실패 유형과 요청 ID를 남기되 비밀 키와 민감한 본문을 기록하지 않습니다.

키 교체와 테스트를 준비한다

비밀 키를 바꾸는 동안 이전 키와 새 키의 허용 기간을 명확히 하고 테스트 이벤트로 검증합니다. 서명 검증이 운영 환경과 테스트 환경에서 다르게 동작하지 않는지도 확인합니다.

현장에 적용할 때의 순서

1. 제공자 공식 방식으로 원시 본문 서명 확인
2. 타임스탬프·이벤트 ID 검증
3. 검증된 이벤트만 업무 큐에 전달

주의할 실패: JSON 본문 내용만 믿고 결제 상태 변경

관찰할 지표: 서명 실패·중복 이벤트·키 교체 오류

적용 전 체크리스트

• 공식 SDK 또는 문서로 원시 본문 서명을 검증한다
• 타임스탬프와 이벤트 ID로 재전송을 막는다
• 서명 실패를 업무 처리 전에 차단한다

참고 자료

Stripe Docs — Resolve Webhook Signature Verification Errors. 웹훅 서명과 원시 본문 검증의 구체적 사례는 Stripe 공식 문서를 참고했습니다. 실제 구현은 사용하는 웹훅 제공자의 규칙을 따라야 합니다.

이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.

#웹훅 #서명검증 #HMAC #API보안 #재전송공격 #멱등성 #이벤트처리 #비밀키 #결제웹훅 #웹개발