Stripe에서 아이덴포턴트한 제휴 수수료: 웹훅 재시도로 인한 이중 결제 방지

(dev.to)

Stripe 웹훅의 재전송 특성으로 인해 발생할 수 있는 중복 결제 및 수수료 지급 문제를 데이터베이스의 고유 제약 조건(Unique Constraint)을 활용한 멱등성 확보로 해결하는 실무적인 방법을 제시합니다.

이 글의 핵심 포인트

1Stripe는 웹훅 전달 실패 시 최대 3일까지 동일 이벤트를 재전송함
2'at-least-once' 전달 방식 특성상 동일한 event.id가 중복 수신될 수 있음
3해결책으로 Stripe의 event.id를 데이터베이스의 고유 제약 조건(Unique Constraint)으로 활용할 것을 권장함
4중복 이벤트 발생 시 500 에러가 아닌 200 OK를 반환해야 불필요한 재시도와 알람을 방지할 수 있음
5invoice.id가 아닌 event.id를 기준으로 키를 생성해야 동일 인보이스 내의 다른 이벤트(예: 환불) 처리에 오류가 없음

이 글에 대한 공공지능 분석

왜 중요한가?

결제 시스템에서 중복 지급은 단순한 오류를 넘어 기업의 현금 흐름과 신뢰도에 치명적인 손실을 초래하기 때문입니다. 특히 자동화된 수수료 정산 로직이 설계 미숙으로 인해 중복 실행될 경우, 발견하기 매우 어렵고 운영 리스크가 큽니다.

어떤 배경과 맥락이 있나?

Stripe와 같은 글로벌 결제 플랫폼은 네트워크 불안정이나 서버 타임아웃에 대비해 웹훅을 재전송하는 'at-least-once' 전달 방식을 채택하고 있습니다. 개발자는 시스템의 불확실성을 전제로 로직을 설계해야 합니다.

업계에 어떤 영향을 주나?

핀테크 및 SaaS 스타트업은 결제 데이터의 무결성을 보장하기 위해 분산 락이나 Redis 같은 복잡한 도구 대신, DB 제약 조건을 활용한 단순하고 강력한 멱등성 패턴을 표준으로 채택하여 인프라 복잡도를 낮출 수 있습니다.

한국 시장에 어떤 시사점이 있나?

국내 PG사 연동 시에도 웹훅 재전송 이슈는 빈번히 발생하므로, 결제 및 정산 모듈 설계 시 이벤트 ID 기반의 멱등성 보장 로직을 아키텍처 초기 단계부터 반영하는 것이 필수적입니다.

이 글에 대한 큐레이터 의견

이 글은 복잡한 분산 시스템 문제를 가장 단순하고 비용 효율적인 방법으로 해결하는 엔지니어링의 정수를 보여줍니다. 많은 개발자가 중복 요청을 막기 위해 Redis 기반의 분산 락이나 별도의 체크 로직을 고민하지만, 이는 네트워크 지연이나 레이스 컨디션(Race Condition)이라는 또 다른 문제를 야기할 수 있습니다. 데이터베이스의 유니크 제약 조건을 활용하는 것은 인프라 복잡도를 낮추면서도 원자성(Atomicity)을 보장받는 가장 확실한 방법입니다.

다만, 모든 상황에서 이 방식이 만능은 아닙니다. 만약 비즈니스 로직이 여러 테이블에 걸쳐 매우 복잡하게 얽혀 있고 트랜잭션 범위가 극도로 넓다면, 단순한 유니크 제약 조건만으로는 부족할 수 있으며 성능 저하의 원인이 될 수도 있습니다. 따라서 개발자는 이벤트 ID를 통한 멱등성 확보를 기본으로 하되, 비즈니스 규모와 데이터 정합성의 중요도에 따라 트랜잭션 격리 수준과 시스템 복잡도를 적절히 조율하는 판단력을 갖춰야 합니다.

원문 보기 →