검증 전 실행을 막습니다
JSON을 읽을 수 있다는 사실과 신뢰할 수 있는 요청이라는 사실은 다릅니다. 검증되지 않은 입력으로 메일을 보내거나 CRM 항목을 만들지 않습니다. 사용하는 공급자의 서명 헤더·알고리즘·원본 본문 요구를 현재 공식 문서에서 확인합니다.
가정한 처리 경계
다음은 공급자 중립적인 의사 절차입니다. 실제 구현은 공식 라이브러리와 규칙에 맞춰야 하며 이 순서만으로 인증 코드가 완성되는 것은 아닙니다.
read_original_request_bytes
verify_supplier_signature_using_server_secret
if verification_fails: reject_without_business_action
validate_supported_event_type_and_action
reserve_delivery_for_duplicate_control
persist_accepted_event
schedule_authorized_business_processing
원본과 비밀값
GitHub의 공식 안내처럼 서명 검증에서는 전송 본문이 바뀌지 않았는지와 안전한 비교 방식이 중요합니다. 중간 계층이 JSON을 다시 직렬화하거나 인코딩을 바꾸는 경우를 확인합니다. 비밀값은 브라우저 코드와 저장소, 오류 로그에 넣지 않습니다.
시험 순서
- 정상 서명과 지원 이벤트를 확인합니다.
- 본문 변경·서명 누락·잘못된 서명을 시험합니다.
- 미지원 이벤트와 중복 전달을 분리합니다.
- 거절된 요청에서 후속 부작용이 없는지 봅니다.
실제 운영의 비밀키로 공개 예시를 만들지 않습니다. 검증 실패 원인을 기록할 때 본문과 서명 전체를 불필요하게 복사하지 않고 필요한 오류 범주를 남깁니다. 인증 실패를 무조건 재시도하면 되는 일시 장애로 분류하지 않습니다.
완료 기준
허용한 공급자의 요청만 정한 이벤트 범위에서 처리돼야 합니다. 정상 요청 한 건의 성공뿐 아니라 위조·변조·중복에서의 거절과 상태를 검수합니다. 공급자별 차이를 숨긴 공통 코드로 모든 웹훅을 안전하게 지원한다고 주장하지 않고 실제 구현과 시험한 범위를 명시합니다.
자주 묻는 질문
- 추측하기 어려운 URL이면 인증이 없어도 되나요?
- URL이 로그나 공유 자료에 남을 수 있습니다. 실제 공급자가 지원하는 인증·서명 검증과 권한 범위를 확인하고 URL을 아는 것만으로 업무를 실행하는 설계에 의존하지 않습니다.
- 서명이 맞으면 같은 요청을 여러 번 처리해도 되나요?
- 진짜 발신자의 재전송도 중복 업무를 만들 수 있습니다. 출처 검증과 요청 중복 방지를 별도 책임으로 두고 전달 식별값의 의미를 확인합니다.
공식 참고자료와 작성 기준
공식 문서는 도구·검색 기능의 근거이며, 위의 점검 순서와 완료 기준은 현랩의 실무 설계 제안입니다. 예시를 실제 고객의 성과나 검색엔진의 보장으로 해석하지 않습니다.