우리의 Stripe 배달 파이프라인 — 체크아웃에서 다운로드까지 30초 안에

Source: Dev.to

흐름

Stripe Checkout → Webhook → Atlas listener → 파일 전달 → 이메일 영수증

평균 약 28초 소요.

단계 1: Stripe 웹훅

우리는 checkout.session.completed를 수신합니다. Stripe가 이를 발생시키는 순간, 웹훅 핸들러가 작동합니다.

우리는 서명을 검증(stripe.webhooks.constructEvent)한 후에 진행합니다. 보안이 최우선입니다.

const event = stripe.webhooks.constructEvent(
  req.body,
  sig,
  process.env.STRIPE_WEBHOOK_SECRET
);

if (event.type === "checkout.session.completed") {
  await handlePurchase(event.data.object);
}

단계 2: 고객 레코드 생성

handlePurchase는 네 가지 작업을 수행합니다:

• 세션에서 고객 이메일과 제품 ID를 추출합니다
• 플랫 파일 데이터베이스에 고객 레코드를 생성합니다
• 24시간 만료되는 다운로드 토큰을 생성합니다
• 배송 이메일을 큐에 넣습니다

우리는 플랫 파일을 사용합니다, Postgres가 아니라. 현재 볼륨에서는 설정이 더 빠르고 Atlas가 자율적으로 읽고 쓸 수 있어 더 쉽습니다.

단계 3: 다운로드 토큰

토큰은 서명된 JWT입니다:

const token = jwt.sign(
  { customerId, productId, email },
  process.env.JWT_SECRET,
  { expiresIn: "24h" }
);

const downloadUrl = `https://whoffagents.com/download?token=${token}`;

다운로드 엔드포인트는 토큰을 검증하고, 접근을 로그에 기록한 뒤 파일을 제공합니다.

단계 4: 배송 이메일

Resend가 이메일을 처리합니다. 템플릿은 간단합니다: 제품명, 다운로드 링크, 만료 안내, 지원 이메일.

await resend.emails.send({
  from: "deliver@whoffagents.com",
  to: email,
  subject: `Your ${productName} is ready`,
  html: deliveryTemplate({ name, downloadUrl, expiresAt })
});

전체 이메일 전송 시간: 2~4초.

우리가 이것을 구축하면서 배운 점

• 웹훅 검증은 절대 타협할 수 없습니다. 검증을 생략하면 누구든 가짜 이벤트를 POST해 무료 다운로드를 트리거할 수 있습니다. 우리는 첫 날부터 이를 올바르게 구현했습니다.
• 멱등성은 중요합니다. Stripe는 동일한 웹훅을 두 번 전송할 수 있습니다. 우리 핸들러는 고객 레코드가 이미 존재하는지 확인한 뒤 생성합니다. 중복 배송이 없습니다.
• 플랫 파일은 초기 규모에서 데이터베이스보다 우수합니다. Postgres를 띄우지 않아도 100명의 고객을 처리할 수 있습니다. 1,000명에 도달하면 마이그레이션할 예정이며, 그때까지 파일이 더 빠르게 배포되고 Atlas가 직접 읽을 수 있습니다.
• 실서비스 전 Stripe CLI로 테스트하세요. stripe listen --forward-to localhost:3000/webhook을 사용하면 로컬에서 실제 테스트 이벤트를 발생시킬 수 있습니다. 이 방법으로 세 가지 버그를 잡았습니다.

수치

• 결제부터 이메일 전송까지 평균 시간: 28초
• 첫 48시간 내 실패한 전송: 0
• 수동 이행 개입: 0

앞으로 예정된 내용

• 다운로드당 라이선스 키 생성
• 다운로드 횟수 제한(제품별 설정 가능)
• 재구매 없이 재다운로드할 수 있는 고객 포털

전체 스택

• 결제: Stripe Checkout
• 웹훅: Express + stripe-node
• 토큰: jsonwebtoken
• 이메일: Resend
• 스토리지: 로컬 파일시스템(규모가 커지면 S3로 전환)
• 오케스트레이션: Atlas가 매일 배송 로그를 모니터링

Whoff Agents를 공개적으로 구축하고 있습니다. Stripe 배송 파이프라인에 대해 질문이 있거나 코드를 보고 싶다면 댓글에 물어보세요.