배관 작업 없이 Webhook 디버깅하기
마지막 업데이트:
모든 Webhook 통합은 똑같은 화려하지 않은 문제로 시작합니다. 제공업체의 서버가 여러분의 코드를 호출해야 하는데, 여러분의 코드는 노트북에서 실행되고, 어떤 것도 노트북에 닿을 수 없습니다. 그래서 실제 작업—서명 검증, 페이로드 형태, 핸들러 로직—을 디버깅하기 전에 먼저 배관 작업을 구축합니다. 터널, 스테이징 배포, 내 컴퓨터로 전달하는 공개 URL 말입니다. 이 글은 이 사이트의 Webhook 테스터와 같은 임시 수신기로 그 단계를 건너뛰는 방법에 관한 것입니다. 주소를 만들고, 제공업체를 그쪽으로 지정하고, 이벤트를 트리거하고, 도착한 것을 정확히 읽으세요. 그런 다음 문서가 아니라 진실을 기준으로 핸들러를 작성하세요.
디버깅 순환, 그리고 그것이 깨지는 곳
건강한 Webhook 순환은 짧습니다. 제공업체에서 이벤트가 발생하고, 제공업체가 서명된 페이로드를 엔드포인트로 POST하고, 엔드포인트가 서명을 검증하고, 본문을 파싱하고, 작업을 수행하고, 200으로 응답합니다. 건강하지 않은 순환—모두가 알아보는 그 순환—은 모든 단계에 안개를 더합니다. 제공업체의 대시보드는 전달이 500으로, 또는 404로, 또는 아예 아무것도 없이 실패했다고 말합니다. 그게 응답한 내 코드였나요, 사이의 프록시였나요, 오타가 있는 엔드포인트 URL이었나요? 재시도는 같은 이벤트 ID로 도착합니다—아니면 같은 결제에 대한 새 이벤트인가요? 문서는 깔끔한 JSON 예시를 보여주지만, 운영 페이로드는 추가 필드, 예시가 평평하게 만든 중첩 객체, 그리고 가끔 예시가 언급한 적 없는 콘텐츠 유형을 담고 있습니다. Stripe와 GitHub의 Webhook 문서(아래 링크)는 모두 같은 규율을 강조합니다—서명을 검증하고, 빠르게 응답하고, 중복을 처리하세요—그리고 실제 전달을 볼 수 있게 되기 전까지 그 어느 것도 연습할 수 없습니다.
깨지는 지점은 흥미로운 로직 안에 있는 경우가 거의 없습니다. 그것은 보냈다고 믿는 것과 실제로 보내진 것 사이의 틈에 있습니다. 프레임워크가 이미 파싱하고 다시 직렬화한 본문에 대해 계산된 서명 헤더, 잘못된 대시보드에서 복사한 비밀, switch 문이 약간 다르게 쓰는 이벤트 유형, 대시보드의 테스트 이벤트에서는 작동하지만 운영의 실제 이벤트에서는 작동하지 않는 핸들러. 이 모든 것은 내 로그 안쪽에서는 보이지 않습니다. 로그는 코드가 첫 번째 잘못된 가정을 한 뒤부터 시작하기 때문입니다. 내 코드가 아닌 무언가에 의해 기록된 캡처된 전달이야말로 순환을 짧게 만드는 확실한 진실입니다.
임시 수신기가 사주는 것
임시 수신기는 모든 것을 받아들이고 보여주는 것만을 일로 삼는 공개 URL입니다. 이 사이트의 Webhook 테스터는 클릭 한 번으로 하나를 만들고, 30분 동안 유지하며, 메서드, 경로와 쿼리, 헤더와 본문(각 최대 256KB)과 함께 최대 50개의 전달을 기록한 뒤 모든 것을 자동으로 삭제합니다. 그것이 사주는 것은 순서입니다. 트래픽을 관찰하려고 반쯤 작성된 핸들러를 공개 머신에 배포하는 대신—그리고 그 후 배포와 핸들러를 동시에 디버깅하는 대신—관찰과 구현을 분리합니다. 먼저, 여러 실제 이벤트가 도착하는 것을 보고 그들의 실제 형태를 배웁니다. 다음으로, 캡처된 페이로드를 기준으로 로컬에서 핸들러를 작성하며, 그것들을 직접 자신의 테스트에 재생할 수 있습니다. 마지막으로, 제공업체를 실제 엔드포인트로 지정하고 이벤트를 한 번 더 트리거합니다. 이제 올바른 전달이 정확히 어떤 모습인지, 핸들러가 그것으로 무엇을 해야 하는지 알기 때문입니다.
대화가 팀 경계를 넘을 때 그것은 증거도 사줍니다. «당신 Webhook은 금액을 문자열로 보낸다»는 논쟁이지만, "amount": "2000"을 보여주는 캡처된 전달은 사실입니다. 같은 캡처는 제공업체 지원 티켓이 묻는 질문—어떤 이벤트 ID, 어떤 타임스탬프, 어떤 서명 헤더가 있었는가—에 로그 고고학 없이 답하고, 누락된 전달이 애초에 보내지지 않았는지, 누군가 업데이트를 잊은 오래된 테스트 주소로 보내졌는지를 확정합니다. 이웃 도구, 같은 철학: 질문이 페이로드가 아니라 리디렉션일 때, HTTP 상태 체인 추적기는 서버의 관점에서 URL이 무엇을 하는지 보여줍니다.
워크플로, 이 도구와 함께
하나: Webhook 테스터를 열고 훅을 만드세요. 수신 URL을 복사하세요—그리고 이 순간부터 그 URL을 자격 증명으로 취급하세요. 그 이유는 다음 섹션에서 설명합니다. 둘: 제공업체의 Webhook 설정에 테스트 엔드포인트로 붙여넣으세요—Stripe, GitHub, 대부분의 제공업체는 여러 엔드포인트를 허용하므로 운영 엔드포인트는 그대로 유지됩니다—또는 여러분이 통제하는 발신자를 디버깅 중이라면 자체 서비스의 구성에 붙여넣으세요. 셋: 정직한 방식으로 이벤트를 트리거하세요. 대시보드의 «테스트 이벤트 보내기» 버튼만이 아니라 제공업체의 실제 흐름(테스트 모드 결제, 일회용 브랜치로의 실제 푸시)을 사용하세요. 테스트 이벤트는 때로 정확히 여러분이 신경 쓰는 필드에서 실제 이벤트와 다르기 때문입니다. 넷: 캡처를 읽으세요. 먼저 메서드와 콘텐츠 유형을 확인하고, 다음으로 서명과 이벤트 헤더를, 다음으로 본문을 어떤 예쁘게 꾸민 보기를 믿기 전에 원시 텍스트로 확인하세요.
다섯: 그 캡처를 기준으로 핸들러를 작성하거나 수정하세요. 수신된 그대로의 원시 본문에 대해 서명을 검증하세요—캡처가 파싱되지 않은 바이트를 보여주는 이유가 바로 그것입니다—그리고 이제 재시도를 통해 안정적임을 확인할 수 있는 이벤트 ID에 대해 핸들러를 멱등하게 만드세요. 여섯: 훅을 삭제하고(또는 30분의 만료를 기다리고), 제공업체에서 테스트 엔드포인트를 제거하고, 전달을 실제 핸들러로 다시 지정하세요. 일곱: 이벤트를 한 번 더 트리거하고 자체 엔드포인트가 응답하는 것을 지켜보세요. 이제 실패한다면, 캡처된 좋은 전달과 핸들러 동작 사이의 차이가 버그의 전부이며, 그것은 추측이 아니라 검사할 수 있는 차이입니다.
안전: URL이 자격 증명입니다
누구나 읽을 수 있는 수신기는 로그인이 필요 없고, 그 편리함에는 주의해야 할 대가가 있습니다. URL 안의 훅 ID가 유일한 자격 증명이며, 전송과 조회 모두를 허용합니다. 스크린샷, 채팅 로그, 화면 공유를 통해 URL을 얻은 사람은 누구나 훅이 살아 있는 동안 캡처되는 모든 페이로드를 읽을 수 있습니다. 그래서 규칙은 비밀번호 규칙입니다. URL을 절대 공개적으로 게시하지 말고, 실시간 운영 피드에 절대 사용하지 말며, 캡처가 30분을 다 채우도록 두지 말고 세션이 끝나면 훅을 삭제하세요. 페이로드도 반대쪽에서 같은 존중을 받을 만합니다. 실제 결제나 푸시 페이로드는 고객 이메일 주소, 주문 세부 정보, 공개 gist에 붙여넣지 않을 메타데이터를 포함할 수 있으며, 캡처된 전달은 바로 그런 종류의 문서입니다. 테스트 모드, 일회용 저장소, 합성 이벤트가 존재하는 것은 디버깅 산출물에 훔칠 가치가 있는 것이 아무것도 포함되지 않게 하기 위해서입니다.
테스터 자체의 제한은 안전 이야기의 일부이며 도구 페이지에 명확히 명시되어 있습니다. 캡처는 훅이 만료되거나 삭제할 때까지만 체커 서버에 저장되고—최대 30분—본문은 256KB로, 훅은 50개 요청으로 제한되며, 수신기는 어떤 것도 가져오거나, 따라가거나, 재생하지 않습니다. 그래서 캡처된 페이로드는 서버의 아웃바운드 트래픽으로 변할 수 없습니다. 그래도 판단은 여러분에게 남습니다. 페이로드가 낯선 사람의 손에 들어가면 문제가 될 것이라면, 그것은 공유 뷰어에 아예 속하지 않습니다. 그 디버깅 세션에는 운영 비밀에 대해 그러하듯 자체 인프라를 사용하세요. 편리한 도구가 자리를 얻는 것은 대부분의 디버깅 나날을 채우는 낮은 민감도의 작업에서입니다.
제한: 수신과 검사만
이 도구가 의도적으로 하지 않는 것은 검사 이후의 모든 것입니다. 전달을 노트북으로 전달하지 않습니다(그것은 터널의 일이며, 핸들러가 존재하고 실시간으로 반복 중일 때 터널이야말로 올바른 도구입니다). 캡처된 요청을 실제 엔드포인트로 재생하지 않습니다. 어떤 것도 변환하거나 서명하지 않습니다. 그리고 30분을 넘는 기록은 유지하지 않습니다. 이러한 부재가 바로 설계입니다. 전달하는 수신기는 여러분의 트래픽이 흐르는 프록시이고, 재생하는 수신기는 발신자이며, 둘 다 30분 받은 편지함보다 큰 신뢰입니다. 테스터를 그것이 맞는 단계—핸들러를 구축하기 전과 구축하는 동안 진실을 보는 것—에 사용하고, 통합이 활성화되는 순간부터는 자체 인증과 로깅 뒤에 있는 자체 엔드포인트가 이어받게 하세요.