프로덕션에 배포하지 않고 Stripe 웹훅을 테스트하는 방법

Source: Dev.to

Approach 1: Stripe CLI

공식적인 방법은 Stripe CLI를 설치하고 로그인한 뒤, 이벤트를 로컬 서버로 포워드하는 것입니다:

stripe login
stripe trigger payment_intent.succeeded

Pros

• 빠른 설정.

Cons

• 모의 이벤트에 일반적인 데이터(플레이스홀더 고객 ID, 금액)가 포함됩니다.
• 터미널을 닫으면 터널이 사라집니다.
• 각 재시작 시 새로운 서명 비밀키가 생성되어 .env를 업데이트하지 않으면 서명 검증이 깨집니다.
• 핸들러가 500을 반환하면 CLI 출력에 오류가 명확히 표시되지 않습니다.

Approach 2: ngrok

ngrok을 사용해 로컬 서버를 직접 노출합니다:

ngrok http 3000

• 생성된 퍼블릭 URL을 Stripe의 웹훅 설정에 붙여넣습니다.
• 테스트 모드 결제에서 실제 이벤트를 받게 되므로 모의 데이터보다 좋습니다.

Drawbacks

• 무료 URL이 세션마다 바뀌어 Stripe 대시보드에서 계속 업데이트해야 합니다.
• 핸들러가 요청 중에 크래시하면 웹훅이 손실됩니다; Stripe의 지수 백오프 재시도를 기다리거나 페이로드를 수동으로 재구성해야 합니다.
• ngrok을 종료하면 요청 히스토리가 사라집니다.

Approach 3: Capture First, Process Later

Stripe를 로컬 서버가 아니라 영구적인 엔드포인트에 연결해 모든 웹훅을 캡처하고 저장합니다. 그런 다음 준비가 되면 캡처된 페이로드를 로컬호스트로 재생합니다.

Create an endpoint

curl -X POST https://hooklab-webhook-testing-and-debugging.p.rapidapi.com/api/v1/endpoints

응답에 퍼블릭 URL이 포함됩니다. 예:

https://hooklab-webhook-testing-and-debugging.p.rapidapi.com/hook/ep_V1StGXR8_Z5j

이 URL을 Stripe의 웹훅 설정에 붙여넣습니다.

Send a test payment

테스트 카드 4242 4242 4242 4242를 사용해 Stripe 대시보드에서 결제합니다. Stripe가 웹훅을 전송하고 HookLab이 이를 캡처합니다.

Inspect the captured request

curl https://hooklab-webhook-testing-and-debugging.p.rapidapi.com/api/v1/endpoints/ep_V1StGXR8_Z5j/requests

응답에 전체 헤더, 본문, Stripe-Signature, 타임스탬프 등이 표시되어 콘솔 로그 디버깅이 필요 없게 됩니다.

Replay to your local server

curl -X POST https://hooklab-webhook-testing-and-debugging.p.rapidapi.com/api/v1/replay \
     -d '{"url":"http://localhost:3000/api/webhooks/stripe"}'

재생은 동일한 헤더, 본문, HTTP 메서드를 사용해 요청을 바로 핸들러로 보냅니다. 크래시가 발생하면 버그를 수정하고 다시 재생하면 되며, Stripe의 재시도 로직을 기다릴 필요가 없습니다.

Why Capture‑and‑Replay Is Worth It

가장 흔한 Stripe 웹훅 버그 세 가지를 더 쉽게 찾을 수 있습니다:

1. 잘못된 이벤트 타입 – charge.succeeded를 처리하려고 하는데 Stripe가 payment_intent.succeeded를 보낼 수 있습니다. 체크아웃 흐름을 캡처하면 Stripe가 발생시키는 모든 이벤트와 순서를 확인할 수 있습니다.
2. 데이터 구조의 놀라움 – event.data.object.customer.email에 접근하려다 customer가 확장된 객체가 아니라 문자열 ID일 경우 실패합니다. 실제 캡처된 페이로드를 보면 정확한 구조를 미리 알 수 있습니다.
3. 예상치 못한 필드 – 가끔 Stripe가 새로운 필드를 추가합니다; 실제 페이로드가 있으면 빠르게 대응할 수 있습니다.

Gotchas Everyone Encounters

• 200 OK를 즉시 반환하세요. Stripe는 5–10초 이내에 응답을 기대합니다. 무거운 처리는 비동기로 수행하지 않으면 Stripe가 전달 실패로 판단하고 재시도하여 중복 이벤트가 발생합니다.
• 실제 테스트 모드 트랜잭션으로 테스트하세요. stripe trigger 명령은 엔드포인트 도달성을 확인하는 데는 좋지만, 페이로드가 미묘하게 다르기 때문에 실제 테스트 결제에서 웹훅을 처리할 때까지 통합이 완전히 검증되지 않습니다.

Getting Started with HookLab

HookLab은 RapidAPI에서 무료 티어(하루 100 호출 및 3 엔드포인트)를 제공하며, 대부분의 Stripe 통합 테스트에 충분합니다.

What’s your webhook testing setup? Feel free to share your approach in the comments.