웹훅 요청 구조의 이해
웹훅은 이벤트가 발생했을 때 서버가 외부 시스템으로 실시간 데이터를 전송하는 일반적인 방법입니다. 웹훅 요청을 수신하고 처리하는 시스템을 개발할 때는 전송된 HTTP 요청의 구조를 정확하게 파악하는 것이 중요합니다. 웹훅 요청은 HTTP 메서드, 헤더, 그리고 본문(Body)으로 구성됩니다.
서버 측에서 웹훅 데이터를 구문 분석(Parsing)하기 전에 전송된 정확한 원시 본문(Raw Body)을 확보하는 것이 디버깅의 첫 단계입니다. 원시 본문의 줄바꿈, 공백, 문자 인코딩 등은 웹훅의 무결성을 검증하거나 데이터를 처리할 때 결과에 직접적인 영향을 미치기 때문입니다.
입력 매개변수 및 제한 사항
웹훅 요청 검사기를 사용할 때는 캡처한 웹훅의 세 가지 구성 요소를 입력합니다. 각 입력 필드는 다음과 같은 사양과 제한 사항을 가집니다.
- 방법: 웹훅 요청에 사용된 HTTP 메서드를 선택합니다. 지원하는 메서드는 POST, PUT, PATCH, GET, DELETE입니다.
- 헤더: 이름: 값 형식으로 한 줄에 하나의 헤더를 입력합니다. 최대 200개의 비어 있지 않은 헤더 줄까지 입력할 수 있으며, 전체 헤더의 글자 수는 최대 100,000자로 제한됩니다.
- 본체: 서버 측 구문 분석 전에 캡처된 정확한 원시 본문을 붙여넣습니다. 본문은 최대 1,000,000자까지 입력할 수 있습니다.
웹훅 본문 형식 분석 및 변환 규칙
이 도구는 입력된 본문의 콘텐츠 유형을 자동으로 감지하여 가독성을 높여줍니다.
- JSON 및 URL 인코딩 데이터: 본문이 JSON 또는 URL로 인코딩된 양식 데이터(URL-encoded form data)인 경우, 도구가 이를 감지하여 구조화된 형태로 포맷된 본문을 출력합니다.
- JSON 파싱의 특성: JSON 본문은 내부적으로
JSON.parse를 사용하여 구문 분석을 수행한 후 다시 정렬됩니다. 이 과정에서 원본 요청에 포함되어 있던 공백, 들여쓰기 및 필드의 원래 배치 순서는 유지되지 않고 재구성됩니다. - 기타 본문 형식: JSON이나 URL 인코딩 형식이 아닌 다른 유형의 본문은 변환 없이 일반 텍스트 상태로 유지됩니다. 본문이 비어 있는 경우에는 포맷된 본문 영역에
(빈 본문)이 표시됩니다.
웹훅 서명 및 타임스탬프 헤더 식별
웹훅을 안전하게 처리하기 위해 많은 제공업체는 요청 헤더에 서명(Signature)이나 타임스탬프를 포함하여 전송합니다.
이 도구는 헤더 목록을 분석하여 signature, hmac, digest 및 일반적인 타임스탬프 명명 규칙과 일치하는 패턴을 가진 헤더를 찾아 서명 필드 영역에 목록으로 보여줍니다. 만약 일치하는 헤더가 발견되지 않으면 공통 서명 또는 웹훅 타임스탬프 헤더를 찾을 수 없습니다.라는 메시지가 출력됩니다.
이 기능은 단순히 특정 이름을 가진 헤더의 존재 여부를 식별하는 역할만 수행합니다. 도구 내부에서 HMAC 값을 직접 계산하거나, 암호화 알고리즘을 실행하거나, 페이로드의 원본 바이트를 검증하거나, 보안 비밀(Secret) 키를 대조하거나, 재전송 공격 방지를 위한 타임스탬프 유효 시간(Replay window)을 검사하는 등의 실제적인 검증 작업은 수행하지 않습니다.
로컬 테스트를 위한 cURL 명령어 생성
검사 프로세스가 완료되면 로컬 개발 환경에서 웹훅 수신 동작을 재현하고 테스트할 수 있도록 복사 가능한 cURL 명령어가 자동으로 생성됩니다.
이 명령어는 사용자가 입력한 메서드와 헤더, 본문 데이터를 그대로 포함하며, 로컬 호스트의 특정 포트를 타겟으로 하도록 고정되어 있습니다. 생성되는 cURL 명령의 대상 주소는 http://localhost:3000/webhooks로 고정 출력되므로, 로컬에서 웹훅 수신 서버를 실행하여 전송 테스트를 진행할 때 유용하게 활용할 수 있습니다.
오류 메시지 및 해결 방법
입력값의 형식이나 크기가 도구의 처리 규칙을 벗어나는 경우 다음과 같은 오류 메시지가 표시됩니다.
먼저 하나 이상의 헤더 또는 요청 본문을 붙여넣습니다.: 입력 필드가 모두 비어 있는 상태에서 검사를 시도할 때 발생합니다.이 도구에는 헤더가 너무 깁니다. 관련이 없거나 반복되는 값을 제거합니다.: 입력된 헤더의 총 글자 수가 100,000자를 초과할 때 발생합니다.이 도구에 비해 몸체가 너무 깁니다. 1,000,000자 미만으로 유지하세요.: 입력된 본문의 크기가 1,000,000자를 초과할 때 발생합니다.헤더 줄이 너무 많습니다. 요청을 200개 이하의 헤더로 유지하세요.: 입력된 헤더의 줄 수가 200줄을 초과할 때 발생합니다.‹line›: 헤더 줄 이(가) 잘못되었습니다. 사용 이름: value.: 특정 헤더 줄이 올바른 키-값 구분자 형식(Name: value)을 따르지 않을 때 발생합니다.본문은 JSON처럼 보이지만 구문 분석할 수 없습니다.: 본문 데이터가 JSON 형식을 띠고 있으나 문법적 오류가 있어 파싱에 실패할 때 발생합니다.양식 본문에 불완전한 퍼센트 이스케이프가 포함되어 있습니다.: URL 인코딩된 양식 데이터 내부에 잘못되거나 끊긴 퍼센트 인코딩 문자가 존재할 때 발생합니다.
개인정보 보호 및 데이터 처리 방침
이 도구를 사용할 때 입력하는 모든 데이터의 처리 작업은 사용자의 웹 브라우저 내부에서만 실행됩니다. BroBroGo는 사용자가 붙여넣은 웹훅 메서드, 헤더, 본문 데이터를 외부 서버로 업로드하거나 저장하지 않습니다.
자주 묻는 질문 (FAQ)
Q. 이 페이지는 실시간 웹훅 콜백을 받을 수 있나요?
A. 아니요. 검사를 위해 캡처된 요청을 여기에 붙여넣으세요. 이 페이지는 퍼블릭 엔드포인트를 생성하거나 콜백을 수신하거나 생성된 테스트 요청을 보내지 않습니다.
Q. 어떤 웹훅 본문 형식을 검사할 수 있나요?
A. JSON 및 URL로 인코딩된 양식 본문이 감지되고 형식이 지정됩니다. 다른 본문은 일반 텍스트로 유지되므로 도구는 XML, 멀티파트 또는 바이너리 콘텐츠를 추측하지 않습니다.
Q. 서명 필드를 찾으면 요청이 진짜라는 것을 증명할 수 있나요?
A. 아니요. 이 도구는 서명 및 관련 타임스탬프 헤더만 표시합니다. 실제 확인에는 보낸 사람의 정확한 서명 규칙, 비밀 또는 공개 키, 원본 요청 바이트가 필요합니다. 서명 필드가 존재한다고 해서 요청이 유효하다는 것이 증명되지는 않습니다.