웹훅을 테스트하려면, 제공업체에 접근 가능한 URL을 제공하고, 실제 이벤트를 트리거한 다음, 핸들러가 페이로드를 수락하고 올바르게 반응하는지 확인해야 합니다. 어려운 점은 앱이 호출자가 아닌 수신자이므로 단순히 "보내기"를 누르고 응답을 읽을 수 없다는 것입니다. 이 가이드는 필요한 도구(검사 서비스, 로컬 터널, 제공업체 트리거)와 핸들러를 처음부터 끝까지 검증하는 반복 가능한 프로세스를 안내합니다.
웹훅이 일반 API보다 테스트하기 어려운 이유
일반적인 API 호출에서는 요청을 제어합니다. 메서드를 선택하고, 본문을 설정하고, 실행한 다음 응답을 읽습니다. 웹훅은 이 순서를 뒤집습니다. 제공업체가 자체 일정에 따라 정의된 페이로드와 함께 사용자에게 요청을 보냅니다. 이러한 역할 역전은 네 가지 테스트 문제를 야기합니다.
첫째, 기본적으로 이벤트를 직접 트리거할 수 없습니다. payment_intent.succeeded 이벤트는 Stripe가 결정할 때만 발생하므로, 이벤트를 강제로 발생시키기 위한 제공업체 도구가 필요합니다.
둘째, 전송은 비동기적입니다. 이벤트는 업스트림 작업이 완료될 때마다 도착하므로, 테스트는 반환 값을 기다리는 대신 인바운드 요청을 캡처해야 합니다.
셋째, 페이로드 형태는 제공업체에 의해 정의됩니다. 핸들러는 GitHub, Stripe 또는 Slack이 보내는 내용을 정확히 파싱해야 합니다.
넷째, 대부분의 제공업체는 요청에 서명합니다. 엔드포인트는 본문을 신뢰하기 전에 서명 헤더를 확인해야 하며, 이를 건너뛰는 테스트는 실제 버그를 숨깁니다. 더 자세한 내용은 웹훅 서명 확인에 대한 가이드를 참조하십시오.
웹훅이 통합에 적합한 패턴인지 아직 결정 중이라면, 웹훅과 폴링 비교 및 웹훅과 WebSocket 비교에서 장단점을 비교해 보세요.
웹훅 테스트 툴킷
동일한 세션에서 다음 네 가지 종류의 도구를 사용하게 될 것입니다: 원시 페이로드를 확인하는 캡처 서비스, 노트북에 연결하는 터널, 실제 이벤트를 발생시키는 제공업체 트리거, 그리고 핸들러를 검증하는 어설션 도구입니다.
1. 검사 및 캡처 서비스
핸들러 코드를 한 줄도 작성하기 전에, 제공업체를 임시 URL로 지정하고 실제로 무엇을 보내는지 확인하십시오. 이러한 서비스는 공용 엔드포인트를 제공하고 모든 요청을 실시간으로 보여줍니다.
webhook.site는 페이지가 로드되는 즉시 고유한 임의의 URL과 이메일 주소를 제공합니다. 여기에 전송된 모든 것은 전체 본문, 헤더, 메서드와 함께 즉시 나타납니다. 무료 URL은 7일 후 만료되며 100개 요청으로 제한되며, 최대 요청 크기는 10MB입니다. 유료 플랜은 영구 URL, 무제한 요청, 그리고 최신 10,000개 요청의 기록을 추가합니다.
Beeceptor는 웹훅 수신기로 사용할 수 있는 무료 HTTPS 엔드포인트를 제공하며, 실시간으로 수신 페이로드를 검사할 수 있습니다. 또한 목(mock) 서버 엔드포인트를 제공하여 동일한 도구에서 캡처하고 시뮬레이션할 수 있습니다.
Pipedream RequestBin은 널리 사용되는 또 다른 요청 캡처 도구입니다. 캡처 서비스는 무료 제한을 자주 변경하므로, 계층별 세부 정보는 현재 문서를 확인하십시오.
이것들을 사용하여 한 가지 질문에 답하십시오: 실제 페이로드는 어떻게 생겼는가? 나중에 반복 가능한 테스트를 만들 때 샘플을 복사해 두십시오.
2. 로컬 개발: 터널을 사용하여 localhost 노출
제공업체는 사용자 머신의 localhost:3000에 도달할 수 없습니다. 터널은 트래픽을 로컬 포트로 전달하는 공개 HTTPS URL을 생성하므로, 편집기에서 핸들러를 실행하고 실시간으로 디버깅할 수 있습니다.
ngrok은 일반적인 선택입니다. 설치하고, 한 번 인증한 다음, 포트를 전달하십시오.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # forwards a public HTTPS URL to localhost:3000
무료 ngrok 계정은 자동으로 선택된 개발 도메인을 얻습니다. 사용자 지정 도메인은 유료 플랜이 필요합니다.
Cloudflare를 선호한다면 cloudflared는 단일 명령으로 빠른 터널을 실행합니다.
cloudflared tunnel --url http://localhost:3000
터널이 출력하는 공개 URL을 제공업체의 웹훅 설정에 붙여넣으면 인바운드 이벤트가 로컬 서버에 도착합니다. 이 패턴에 대한 자세한 내용은 웹훅 서비스로 localhost API를 테스트하는 방법을 참조하십시오.
3. 제공업체에서 테스트 이벤트 트리거
캡처 URL은 무엇인가가 전송된 후에만 유용합니다. 대부분의 주요 제공업체는 온디맨드로 테스트 이벤트를 발생시키는 도구를 제공하므로, 실제 결제나 푸시를 생성할 필요가 없습니다.
Stripe CLI는 가장 명확한 예시입니다. stripe listen 명령은 Stripe 샌드박스에서 실시간 이벤트를 로컬 경로로 전달하며, 앱 구성에 넣을 웹훅 서명 비밀을 출력합니다.
# Forward all events to your local handler:
stripe listen --forward-to localhost:3000/webhooks
# Filter to specific events only:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
리스너가 실행 중인 상태에서 stripe trigger는 테스트 이벤트를 발생시킵니다. 트리거링은 적절히 지원되는 API 객체를 생성하며 부수 효과가 있습니다: payment_intent.succeeded는 또한 payment_intent.created를 발생시킵니다.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # list every supported event
GitHub는 재생할 수 있는 짧은 전달 기록을 유지합니다. 리포지토리로 이동한 다음, 설정(Settings), "코드 및 자동화" 아래의 웹훅(Webhooks)으로 이동합니다. 웹훅 URL을 클릭하고, "최근 전달(Recent deliveries)" 탭을 열고, 전달 GUID를 클릭한 다음, "재전송(Redeliver)"을 클릭합니다. 두 가지 제약 사항이 있습니다: 지난 3일 이내의 전달만 재전송할 수 있으며, 리포지토리에 대한 관리자 액세스 권한이 필요합니다. GitHub는 실패한 전달을 자동으로 재전송하지 않으므로, 재생은 수동입니다.
Slack 수신 웹훅은 테스트하기 가장 간단합니다. 웹훅 URL에 JSON을 POST하여 메시지를 보냅니다. 최소 페이로드는 text 필드뿐입니다.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
Slack 웹훅 URL은 비밀입니다. Slack은 유출된 URL을 취소하므로, 클라이언트 측 코드나 공개 리포지토리에서 제외하십시오.
4. 핸들러 어설션
캡처 및 트리거링은 기본 작동을 증명합니다. 하지만 핸들러가 올바른지는 증명하지 않습니다. 최종 도구는 조작된 페이로드를 전송하고 응답과 부수 효과를 확인합니다. 가장 기본적으로 이는 대표적인 본문을 가진 curl 명령입니다.
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
단일 curl은 스모크 테스트에는 좋습니다. 하지만 CI에서 실행되는 반복 가능하고 검증된 테스트를 원할 때는 부족합니다. 여기서 전용 API 도구가 제 역할을 합니다.
Apidog로 웹훅 테스트하기
Apidog는 API 설계, 디버깅, 테스트, 목(mock) 설정 및 문서화를 위한 올인원 API 플랫폼입니다. 전용 "웹훅 수신함"은 없으므로, 이 섹션에서는 페이로드 제작, 저장, 응답 어설션, 목 서버를 통한 제공업체 대리 역할 등 Apidog가 실제로 잘하는 점에 대해 솔직하게 설명합니다.
샘플 페이로드를 재사용 가능한 요청으로 제작 및 저장
webhook.site에서 캡처한 페이로드(또는 제공업체 문서에서 복사한 페이로드)를 Apidog 요청으로 만드십시오. 메서드를 POST로 설정하고, JSON 본문을 붙여넣고, 핸들러가 확인하는 서명 헤더를 포함하여 제공업체가 보내는 헤더를 추가하십시오.
해당 요청을 엔드포인트에 저장하십시오. 이제 curl 명령을 매번 다시 입력하는 대신, 알려진 올바른(또는 의도적으로 잘못된) 페이로드를 핸들러에 POST하는 반복 가능하고 버전 관리되는 방법을 갖게 됩니다.
시각적 어설션 빌더로 응답 확인
페이로드를 보내는 것은 테스트의 절반입니다. 나머지 절반은 핸들러가 무엇을 반환하는지 확인하는 것입니다. 요청 또는 시나리오 단계에서 Post Processors를 열고, “+ 추가”를 클릭한 다음, “어설션”을 선택하십시오. Apidog는 코드 없이 구성할 수 있는 유효성 검사 규칙을 추가합니다.
응답 본문에 어설션을 지정하고 JSON 루트에 $를 사용하십시오. 예를 들어, $.data.status를 대상으로 지정하고, 조건을 Equals로 설정한 다음, succeeded와 비교하십시오. 요청을 실행하면 결과가 어설션 탭에 표시됩니다. 시각적 어설션은 값을 문자열로 비교합니다. 유형에 정확한 검사(실수, 부울)가 필요할 때는 Postman 호환 pm.test 구문을 사용하는 사용자 지정 스크립트로 전환하십시오.
이는 "200을 반환했다"는 것을 "200을 반환했으며, 상태 필드가 성공(succeeded)이고, 주문 ID가 일치한다"로 바꿉니다. 성공 경로, 필드 누락 사례, 잘못된 서명 거부를 포함하도록 여러 어설션을 하나의 시나리오로 구축하십시오.
목 서버를 사용하여 제공업체 대리 역할 수행
때로는 다른 방향을 테스트하고 싶을 때가 있습니다: 스택의 서비스가 제공업체를 호출하는 경우입니다. 로컬 테스트 중에는 실제 제공업체를 전혀 사용하고 싶지 않을 수 있습니다. Apidog의 목 서버를 사용하면 이를 대신할 수 있습니다.
Apidog는 세 가지 목(mock) 유형을 제공합니다. 로컬 목(Local Mock)은 데스크톱 클라이언트와 함께 실행되며 클라이언트가 열려 있는 동안에만 작동합니다. 클라우드 목(Cloud Mock)은 Apidog 서버에 호스팅되며 24시간 내내 실행되고 켜거나 끌 수 있습니다(기본적으로 꺼져 있습니다). 러너 목(Runner Mock)은 자체 호스팅 러너 인프라에서 실행되며 팀 전체에서 공유됩니다. 각 HTTP 엔드포인트에는 Mock 모듈이 있습니다. 디자인 모드의 API 탭 또는 디버그 모드의 Mock 탭에서 목 URL을 복사하십시오. /로 시작하는 경로만 목 환경으로 라우팅됩니다. 테스트 중에 코드를 해당 목 URL로 지정하면, 실제 API 호출이나 부수 효과 없이 통합이 예측 가능한 제공업체 응답을 받습니다.
Apidog CLI로 CI에서 웹훅 테스트 실행
시나리오가 로컬에서 통과하면, Apidog CLI를 사용하여 푸시할 때마다 실행하십시오. Node.js v16 이상이 필요합니다.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # verify install
시나리오의 CI/CD “명령줄” 탭에서 액세스 토큰과 ID를 전달하여 저장된 시나리오를 온라인으로 실행하십시오.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
여기서 -t는 테스트 시나리오, -e는 환경(필수), -d는 테스트 데이터(CSV 또는 JSON 파일 경로, 또는 저장된 데이터 세트 ID), 그리고 -r은 cli, html, json, junit를 허용하는 리포터(reporters)를 설정합니다. 전체 명령줄 사용법은 Apidog CLI 튜토리얼을 참조하십시오.
자신만의 웹훅 테스트를 시각적으로 구축하고 검증하고 싶으신가요? Apidog를 무료로 사용해 보세요. 신용 카드 정보는 필요하지 않습니다.
단계별 웹훅 테스트 워크플로
도구들을 한데 모아, 반복 가능한 순서는 다음과 같습니다.
- 실제 페이로드 검사. 제공업체를 webhook.site URL로 지정하고 실제 이벤트 하나를 캡처하십시오. 본문 형태, 헤더, 서명 형식을 기록해 두십시오.
- 코드에 접근. 로컬에서 핸들러를 시작하고,
ngrok http 3000또는cloudflared로 터널을 열고, 공개 URL을 제공업체의 웹훅 구성에 넣으십시오. - 실제 이벤트 트리거.
stripe trigger, GitHub의 재전송(Redeliver) 버튼 또는 Slack POST를 사용하여 터널을 통해 실제 이벤트를 보내십시오. - 서명 처리 확인. 유효한 서명으로 동일한 페이로드를 보내고, 변조된 서명으로 다시 보내십시오. 핸들러는 첫 번째는 수락하고 두 번째는 거부해야 합니다.
- 응답 및 부수 효과 확인. 페이로드를 Apidog 요청으로 저장하고, 응답 본문과 상태에 대한 어설션을 추가하며, 데이터베이스 행 또는 다운스트림 호출이 발생했는지 확인하십시오.
- 자동화. 시나리오를 Apidog CLI로 옮겨 모든 변경 사항에 대해 CI에서 실행되도록 하십시오.
웹훅 시스템을 단순히 사용하는 것이 아니라 직접 설계하는 경우, 신뢰할 수 있는 웹훅을 설계하는 방법과 결제 웹훅 모범 사례에서 재시도, 멱등성 및 보안에 대해 다룹니다. 더 넓은 관점에서, 웹훅 API 가이드와 웹훅 및 이벤트 기반 아키텍처는 웹훅이 더 큰 시스템에서 어디에 적합한지 설명합니다.
자주 묻는 질문
웹훅을 어떻게 테스트합니까?
제공업체에 접근 가능한 URL을 제공하고, 실제 또는 테스트 이벤트를 트리거한 다음, 핸들러가 페이로드를 수신하고, 서명을 확인하고, 올바른 상태를 반환하며, 예상되는 부수 효과를 수행하는지 확인하십시오. 먼저 실제 페이로드를 캡처한 다음, 어설션을 포함한 반복 가능한 요청을 구축하여 테스트가 매번 동일하게 실행되도록 하십시오.
로컬에서 웹훅을 어떻게 테스트합니까?
로컬 포트에서 핸들러를 실행한 다음, 터널을 사용하여 제공업체가 사용자 머신에 도달할 수 있도록 노출하십시오. ngrok http 3000 또는 cloudflared tunnel --url http://localhost:3000을 사용하고, 공개 HTTPS URL을 제공업체의 웹훅 설정에 붙여넣고 이벤트를 트리거하십시오. 인바운드 요청은 로컬 서버에 도착하며, 거기서 중단점을 설정하고 실시간으로 검사할 수 있습니다.
Postman으로 웹훅을 어떻게 테스트합니까?
Postman은 조작된 페이로드를 엔드포인트에 POST하고 응답을 확인할 수 있지만, 자체적으로 실제 인바운드 웹훅을 수신할 수는 없습니다. Apidog도 마찬가지입니다: 제공업체의 페이로드와 헤더를 사용하여 요청을 만들고, 응답 본문과 상태에 대한 어설션을 추가하며, 재사용 가능한 테스트로 저장합니다. 진정한 인바운드 이벤트를 캡처하려면 해당 도구를 캡처 서비스 또는 터널과 페어링해야 합니다.
Stripe 웹훅을 어떻게 테스트합니까?
Stripe CLI를 사용하십시오. stripe listen --forward-to localhost:3000/webhooks를 실행하여 샌드박스 이벤트를 핸들러로 전달하고 서명 비밀을 얻으십시오. 그런 다음 stripe trigger payment_intent.succeeded (또는 stripe trigger --help에서 제공하는 모든 이벤트)를 실행하여 실제 테스트 이벤트를 발생시키십시오. 트리거링은 지원되는 API 객체를 생성하며 연쇄 반응을 일으킬 수 있으므로, payment_intent.succeeded는 또한 payment_intent.created를 발생시킵니다.
Slack 웹훅을 어떻게 테스트합니까?
수신 웹훅 URL에 JSON을 POST하십시오. 최소한의 유효한 페이로드는 Content-type: application/json 헤더와 함께 전송되는 {"text":"Hello, world."}입니다. 성공적인 테스트는 메시지를 구성된 채널에 게시합니다. Slack은 유출된 웹훅 URL을 취소하므로 URL을 비밀로 유지하십시오.
웹훅 URL을 어떻게 테스트합니까?
URL에 샘플 POST를 보내고, 성공 상태를 반환하고 올바르게 작동하는지 확인하십시오. 가장 빠른 확인은 대표적인 본문을 가진 단일 curl입니다. 실제 테스트의 경우, 먼저 실제 페이로드를 캡처하고, 유효한 서명과 유효하지 않은 서명 모두로 전송하며, 단순히 200을 확인하는 대신 응답과 부수 효과를 확인하십시오.