업무 웹훅을 받으면 처리하기 전에 왜 서명을 확인해야 할까요?

업무 웹훅 수신기는 요청 본문을 처리하기 전에 제공자가 정한 방식으로 서명을 확인해야 합니다. GitHub의 방식을 예로 검증 대상 바이트와 비밀값 관리를 구분하고, 중복 전달에 대한 처리도 따로 정하도록 권합니다.

수신 주소로 들어온 요청을 바로 처리해도 될까요?

외부 시스템의 변경 알림을 받아 회사의 업무 기록을 갱신하는 상황을 가정해 보겠습니다. 요청이 정해 둔 주소로 왔다는 사실만으로 발신자가 확인되는 것은 아닙니다. GitHub의 웹훅 검증 안내는 GitHub에서 보냈고 전송 중 변조되지 않은 요청인지 확인하기 위해 후속 처리 전에 서명을 검증하도록 설명합니다.

탱탱소프트는 연동 의뢰서에 발신 서비스와 서명 규격을 명시하도록 권합니다. 이 글은 GitHub 웹훅을 예로 들며, 결제·문자·다른 업무 서비스도 같은 헤더를 쓴다는 뜻은 아닙니다. 아래 서버 이미지는 요청을 받는 시스템의 개념 장면이지 실제 회사 장비나 보안 점검 결과가 아닙니다.

AI로 생성한 개념 이미지. 실제 사업장 사진이 아닙니다.

서명은 어떤 데이터와 비교하나요?

GitHub는 웹훅에 설정한 비밀값과 요청 본문을 사용해 만든 HMAC-SHA256 서명을 X-Hub-Signature-256 헤더로 전달합니다. 수신기는 같은 비밀값과 원래 본문으로 계산한 값을 비교합니다. 문서의 Python 예시는 원본 요청 본문을 검증 대상으로 명시하며, 프록시 등이 검증 전에 본문이나 헤더를 바꾸지 않았는지 확인하도록 안내합니다.

탱탱소프트는 JSON을 읽어 업무 값을 처리하는 단계와 원래 요청 바이트로 서명을 검증하는 단계를 구분하도록 권합니다. JSON을 다시 문자열로 만들면 공백이나 표현이 달라질 수 있으므로 그것을 원본과 같은 값이라고 가정하지 않습니다. 실제 구현은 제공자의 공식 라이브러리와 서버 프레임워크의 본문 읽기 방식을 함께 대조해야 합니다.

GitHub 문서는 일반적인 단순 동등 비교 대신 타이밍 공격에 견디는 비교 수단을 사용하도록 안내합니다. 비밀값을 정하지 않은 웹훅에는 해당 서명 헤더가 없을 수 있다는 설명도 있습니다. 헤더 누락을 검증 성공으로 바꾸지 말고 서비스 계약에 맞는 실패 처리를 정해야 합니다.

서명이 맞으면 같은 알림을 다시 처리해도 되나요?

서명 검증과 중복 처리는 다른 문제입니다. GitHub의 웹훅 권장사항은 X-GitHub-Delivery를 전달 식별자로 쓰는 방법을 설명하며, 재전달에서는 원래 전달과 같은 값이 유지된다고 밝힙니다. 이 식별자는 서명을 대신하는 비밀값이 아닙니다.

탱탱소프트의 운영 제안은 서명 확인을 마친 요청에 대해 전달 식별자와 업무 처리 상태를 기록하고, 재전달 때 이미 끝난 작업을 다시 실행할지 판단하는 것입니다. 식별자 저장만으로 모든 중복이나 동시 실행 문제가 해결되는 것은 아닙니다. 아래 연결망은 알림의 전달 경로를 표현한 개념 삽화입니다.

AI로 생성한 개념 이미지. 실제 사업장 사진이 아닙니다.

의뢰 전에 무엇을 합의해야 할까요?

서명 규격, 원문 본문을 확보할 위치, 검증 실패 시 처리, 전달 식별자 보관 범위와 재처리 조건을 정합니다. GitHub는 비밀값을 코드에 직접 넣거나 저장소에 올리지 말고 서버가 접근할 수 있는 안전한 위치에 보관하도록 안내합니다. 문의 문서에도 비밀값 대신 설정 책임자와 관리 방식을 적는 편을 권합니다.

청주·충북 기업이 외부 서비스를 연동한다면 정상 알림뿐 아니라 헤더 누락, 본문 변경, 동일 알림 재전달을 시험 범위에 포함할 수 있습니다. 탱탱소프트는 홈페이지·웹서비스와 업무 자동화를 구축하는 청주 기반 스튜디오입니다. 이 글은 연동 요구사항을 정리하는 기준이며 개별 서비스의 보안 검증 완료나 사고 방지 실적이 아닙니다.

참고 자료

• GitHub Docs: Validating webhook deliveries
• GitHub Docs: Best practices for using webhooks