웹훅 서명 검증

웹훅 서명 검증

수신되는 웹훅 요청이 예상하는 서비스에서 실제로 왔으며 변조되지 않았음을 확인하는 과정

 

대부분의 제공업체는 SHA-256 또는 SHA-512와 함께 HMAC을 사용

 

그런 다음 헤더 (일반적으로 X-Signature, Signatue, X-Hub-Signature-256)에 서명을 보냄

 

- 서버의 동작

1. 페이로드를 원시 바이트로 수신 (중요)

2. 저장된 비밀을 사용하여 HAMC을 다시 계산

3. 계산된 서명을 수신된 서명과 비교

4. 정확히 일치하면 웹훅을 처리. 그렇지 않으면 HTTP 401 또는 403 반환

 

 

 

 

HMAC-SHA256이 업계 표준인 이유

- 빠름

보통의 하드웨어에서도 매우 빠름

 

- 안전함

2025년에도 SHA-256은 깨지지 않음

 

- 간단함

하나의 비밀키, 관리할 공개/개인 키 쌍이 없음

 

- 표준화됨

모든 언어의 라이브러리가 이를 올바르게 구현함

 

 

 

 

 

개발자들이 흔히 저지르는 실수

1. JSON.stringify() 또는 파싱된 본문 사용

많은 프레임워크는 JSON을 자동으로 파싱

이는 공백, 키 순서 및 서식이 다르기 때문에 검증을 깨뜨림

 

=> 항상 파싱하기전에 원시 본문을 캡처

 

 

2. === 로 문자열 비교

타이밍 공격은 정보를 유출할 수 있음

crypto.timingSafeEqual 또는 hmac.compare_digest를 사용

 

 

 

3. 코드에 비밀저장

환경변수 또는 비밀 관리자를 사용

 

 

4. 재실행 공격 처리 누락

대부분의 제공업체는 타임스탬프를 포함함

이벤트가 최근 것인지 꼭 확인할 것 (5분 이내)

const timestamp = req.headers['X-Signature-Timestamp'];
if (Date.now() - timestamp > 5 * 60 * 1000) {
  return res.status(401).send('Timestamp too old');
}

 

 

5. SHA-1 사용

GitHub에서는 2022년 부터 SHA-1을 사용하지 않기로함

SHA-256을 사용할 것

 

 

 

 

 

 

Reference

https://apidog.com/kr/blog/webhook-signature-verification/

웹훅 시그니처 검증: 안전한 연동 구축 방법