Source: Dev.to

로컬호스트에서 Stripe 웹훅을 머리 아프게 하지 않고 받는 방법

개발 중에 Stripe 웹훅을 테스트하려면 로컬 서버가 외부에서 접근 가능해야 합니다.
전통적인 방법은 ngrok 같은 터널링 서비스를 사용하는 것이지만, 설정이 번거롭고 때때로 연결이 끊기기도 합니다.

다행히 Stripe CLI를 사용하면 별도의 터널링 없이도 로컬에서 바로 웹훅을 받을 수 있습니다. 아래에서는 가장 간단한 설정 과정을 단계별로 설명합니다.

---

1️⃣ Stripe CLI 설치

# macOS (Homebrew)
brew install stripe/stripe-cli/stripe

# Windows (Scoop)
scoop install stripe

# Linux (curl)
curl -L https://github.com/stripe/stripe-cli/releases/download/vX.Y.Z/stripe_X.Y.Z_linux_x86_64.tar.gz | tar xz
sudo mv stripe /usr/local/bin/

Tip: 최신 버전은 stripe version 명령어로 확인할 수 있습니다.

---

2️⃣ 로그인 및 API 키 연결

stripe login

명령어를 실행하면 브라우저가 열리고 Stripe 계정에 로그인하라는 메시지가 표시됩니다.
로그인 후 CLI가 자동으로 API 키와 시크릿 키를 구성합니다.

---

3️⃣ 로컬 서버에 웹훅 엔드포인트 만들기

예시로 Express(Node.js) 를 사용합니다.

// server.js
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const event = req.body;

  // 여기서 이벤트 타입에 따라 로직을 구현
  console.log('🔔 Received event:', event.type);
  res.sendStatus(200);
});

app.listen(4242, () => console.log('🚀 Server listening on http://localhost:4242'));

node server.js

Note: 포트 번호(4242)는 자유롭게 바꿔도 됩니다. 다만 이후 단계에서 동일하게 사용해야 합니다.

---

4️⃣ Stripe CLI 로컬 웹훅 포워딩

stripe listen --forward-to localhost:4242/webhook

• stripe listen 은 Stripe가 발생시키는 모든 이벤트를 실시간으로 수신합니다.
• --forward-to 옵션은 수신한 이벤트를 지정한 로컬 엔드포인트로 바로 전달합니다.

명령어를 실행하면 다음과 비슷한 출력이 나타납니다.

> Ready! Your webhook endpoint is set up at https://api.stripe.com/v1/webhook_endpoints/wh_...
   Forwarding events to http://localhost:4242/webhook

이제 Stripe 대시보드에서 Test webhook 버튼을 눌러도 로컬 서버가 이벤트를 받게 됩니다.

---

5️⃣ 특정 이벤트만 수신하기 (선택 사항)

전체 이벤트를 받는 대신 특정 이벤트만 받고 싶다면 --events 플래그를 사용합니다.

stripe listen --forward-to localhost:4242/webhook --events payment_intent.succeeded,charge.refunded

---

6️⃣ 로컬에서 이벤트 트리거하기

CLI를 통해 직접 이벤트를 발생시킬 수도 있습니다.

stripe trigger payment_intent.created

위 명령은 payment_intent.created 이벤트를 생성하고, 앞서 설정한 로컬 엔드포인트로 전달합니다.

---

📌 정리

이제 ngrok 같은 외부 터널링 없이도 로컬에서 Stripe 웹훅을 손쉽게 테스트할 수 있습니다.
문제가 발생하거나 더 복잡한 시나리오가 필요하면 Stripe CLI 공식 문서(https://stripe.com/docs/stripe-cli)를 참고하세요. Happy coding!

Hooklink으로 Stripe 웹훅 로컬 테스트

Stripe 결제를 통합해 본 적이 있다면 이미 익숙한 상황일 것입니다. Stripe는 공개 URL로 웹훅 이벤트를 전송하지만, 개발 서버는 localhost:3000에서 실행됩니다. 실시간으로 이벤트를 내 머신으로 받아야 다음을 할 수 있습니다:

• 결제 흐름 테스트
• 구독 변경 처리
• 엣지 케이스 페이로드 디버깅

이 글에서는 Hooklink이라는 웹훅‑to‑localhost 도구를 사용해 이 격차를 메우는 방법을 단계별로 살펴보겠습니다. Hooklink은 다음을 제공합니다:

• 영구 서브‑도메인
• 서명 검증
• 이벤트 필터링
• 재생 기능

일반적인 우회 방법은 왜 안 될까?

Source: …

단계별 가이드: 로컬 머신에서 Stripe 이벤트 실시간 수신하기

1. Hooklink 계정 만들기

1. app.hooklink.net/register 로 이동해 회원가입합니다.
2. 무료 플랜은 주당 2,500 요청을 제공하므로 개발용으로 충분합니다.

2. Stripe 엔드포인트 만들기

1. Hooklink 대시보드에서 Endpoints → Create Endpoint 로 이동합니다.

2. Stripe 템플릿을 선택합니다 (가장 빠른 방법).

   • Integrations → Stripe 카드 찾기 → Use Template

   대화 상자가 다음 필드를 자동으로 채워줍니다:

3. Local target URL을 프로젝트의 웹훅 라우트에 맞게 수정한 뒤 Create 를 클릭합니다.

엔드포인트가 이제 영구적이고 기억하기 쉬운 URL 로 활성화됩니다:

https://stripe-yourname.hooklink.net

참고: 이 URL은 절대 변경되지 않으므로 Stripe 대시보드에서 계속 업데이트할 필요가 없습니다.

3. Hooklink URL을 Stripe에 등록하기

1. Stripe 대시보드에서 Developers → Webhooks → Add endpoint 로 이동합니다.
2. Hooklink URL https://stripe-yourname.hooklink.net 을 붙여넣습니다.
3. 수신하고 싶은 이벤트를 선택합니다 (예: payment_intent.succeeded, checkout.session.completed, customer.subscription.created).
4. Add endpoint 를 클릭합니다.

4. 서명 검증 활성화하기

Stripe는 모든 웹훅에 Stripe-Signature 헤더에 HMAC‑SHA256 서명을 포함합니다.

1. Stripe 웹훅 설정에서 Signing secret (whsec_ 로 시작)을 복사합니다.

2. Hooklink 엔드포인트 설정에서 Signature Verification 을 활성화합니다:

   • Algorithm: HMAC‑SHA256
   • Header: Stripe-Signature
   • Signing secret: Stripe에서 복사한 값을 붙여넣기

Hooklink은 Stripe 서명 형식(t=timestamp,v1=signature)을 기본적으로 파싱하고, 서명된 페이로드를 {timestamp}.{body} 형태로 구성한 뒤 상수 시간 비교를 수행합니다. 또한 재생 공격 방지를 위해 기본 5분 허용 오차 창을 사용해 타임스탬프를 검증합니다.

5. Hooklink CLI 설치 및 인증

# 전역 설치
npm install -g @hooklink/cli

대시보드 Dashboard → API Keys 에서 API 키를 생성한 뒤 로그인합니다:

hooklink login --key hlk_your_api_key_here

6. Stripe 엔드포인트에 연결하기

hooklink connect stripe

다음과 유사한 출력이 나타납니다:

$ hooklink connect stripe

  Connection Details:
    Version:      v1.2.0
    Endpoint:     stripe
    Webhook URL:  https://stripe-yourname.hooklink.net
    Target:       http://localhost:3000/api/webhooks/stripe

  Waiting for webhooks...

이제 모든 Stripe 웹훅이 지속적인 WebSocket 연결을 통해 실시간으로 로컬 서버에 전달됩니다.

7. 흐름 테스트하기

1. Stripe 웹훅 설정에서 Send test webhook 을 클릭하고 이벤트를 선택합니다 (예: payment_intent.succeeded).
2. 터미널에 다음과 같은 로그가 표시됩니다:

stripe   POST --> payment_intent.succeeded
stripe   POST  payment_intent.succeeded
stripe   POST  push
github   POST <-- 200   8ms
preview  GET      /dashboard  200

설치

npm install -g @hooklink/cli

인증

hooklink login --key hlk_your_key

엔드포인트 연결

• 단일 엔드포인트 (Stripe)

  hooklink connect stripe

• 다중 엔드포인트 (Stripe, GitHub, Preview)

  hooklink connect stripe,github,preview

유용한 명령어

• 최근 웹훅 로그 보기

  hooklink logs --endpoint stripe

• 연결 상태 확인

  hooklink status

Hooklink를 사용하는 이유?

Stripe 웹훅을 로컬에서 테스트하는 것이 고통스러울 필요는 없습니다. Hooklink를 사용하면 다음을 얻을 수 있습니다:

• 재시작 후에도 유지되는 영구 URL
• 내장된 Stripe 서명 검증
• 이벤트 필터링 및 소스 IP 허용 목록
• 원클릭 웹훅 재생
• 무료 전체 요청 로깅

무료 플랜은 주당 2,500 요청을 3개의 엔드포인트에 걸쳐 전체 요청 로깅과 함께 제공합니다—대부분의 개발 워크플로에 충분합니다.

빠른 시작 (가입 필요 없음)

npx @hooklink/cli listen 3000

30 초 이내에 공개 웹훅 URL을 받을 수 있습니다.