기술 · 출처 기반 답변

웹훅 서명 검증(Webhook Signature Verification)이란?

웹훅 서명 검증은 수신자가 들어오는 HTTP 요청에 첨부된 암호화 서명을 검증하는 보안 절차입니다. 페이로드가 신뢰할 수 있는 제공업체에서 발송되었고 전송 중에 변경되지 않았음을 보장합니다.

정의

웹훅 서명 검증은 웹훅 이벤트의 출처를 인증하는 메커니즘입니다. Resend나 SendGrid 같은 제공업체는 이메일 이벤트에 대한 알림을 보낼 때 시크릿 키로 서명한 페이로드의 해시를 함께 포함합니다. 수신 서버는 같은 시크릿 키로 해시를 다시 계산해 요청 헤더에 담긴 서명과 비교합니다.

처리 과정

제공업체는 공유 시크릿과 요청 본문으로 HMAC 해시를 생성합니다. 이 해시는 보통 X-Signature 또는 비슷한 이름의 헤더로 전송됩니다. 수신자는 원시 요청 본문과 서명 헤더를 가져옵니다. 그런 다음 공유 시크릿으로 자체 HMAC 해시를 계산합니다. 계산한 해시가 헤더 값과 일치하면 요청은 진본입니다. 서로 다르면 권한 없는 요청으로 거부합니다.

발신자에게 중요한 이유

검증하지 않으면 웹훅 URL을 아는 누구나 서버에 가짜 데이터를 보낼 수 있습니다. 전달된 이메일을 반송된 것으로 표시하는 등 데이터베이스가 잘못 업데이트될 수 있습니다. 검증을 구현하면 스푸핑 공격을 막고, 애플리케이션이 이메일 인프라가 트리거한 정상적인 이벤트에만 반응하도록 할 수 있습니다.

운영 참고 사항

흔한 실수는 서명을 검증하기 전에 요청 본문을 JSON 객체로 파싱하는 것입니다. JSON 파서는 공백이나 키 순서를 바꿀 수 있어서 결과 문자열이 제공업체가 사용한 원본 페이로드와 일치하지 않을 수 있습니다. 검증 실패를 피하려면 HMAC 계산에는 항상 파싱하지 않은 원시 요청 본문을 사용하세요.

구현 예시

Node.js 환경에서는 개발자가 crypto 모듈로 제공업체 시크릿을 사용해 원시 본문의 hmac sha256 해시를 만듭니다. 그런 다음 타이밍 공격을 막기 위해 상수 시간 비교 함수로 이 결과를 서명 헤더와 비교합니다. SendHQ는 https://sendhq.cc/tools에서 웹훅 설정에 앞서 필요한 경우가 많은 다양한 이메일 설정을 관리하도록 돕는 무료 도구를 제공합니다.

팀에서 자주 묻는 질문

시크릿 키가 유출되면 어떻게 되나요?

시크릿 키가 유출되면 공격자가 서버가 유효한 요청으로 받아들일 가짜 요청에 서명할 수 있습니다. 제공업체 대시보드에서 즉시 시크릿 키를 교체하고 서버 환경 변수를 업데이트해야 합니다.

HTTPS를 쓰면 서명 검증이 필요 없나요?

아니요. HTTPS는 전송 중인 데이터를 암호화하고 서버 신원을 검증하지만, 요청을 보내는 특정 클라이언트가 허가된 이메일 제공업체인지는 검증하지 않습니다.

단순한 API 키 대신 HMAC을 사용하는 이유는 무엇인가요?

HMAC 서명은 메시지 내용이 변조되지 않았음을 증명합니다. 헤더의 고정 API 키는 발신자가 키를 알고 있다는 것만 증명하며 페이로드가 온전하다는 것은 증명하지 못합니다.

1차 출처

Resend 문서 — Resend
Postmark 개발자 문서 — Postmark
SendGrid 문서 — Twilio SendGrid