중복 처리와 타임아웃 해결, 안정적인 Webhook 설계 전략

Context

Webhook은 At-least-once 전달 방식으로 인해 중복 이벤트 수신 가능성이 높음. 동기식 처리 구조는 핸들러 타임아웃 발생 시 재전송을 유발하여 중복 처리 위험을 증가시킴. 신뢰할 수 없는 페이로드 수신으로 인한 보안 취약점 존재.

Technical Solution

• eventId 기반의 Upsert 로직을 적용하여 동일 이벤트 중복 처리 방지 및 멱등성 확보
• Stripe SDK의 constructEvent 함수를 활용한 Signature Verification 수행으로 페이로드 위변조 차단
• 요청 수신 즉시 200 OK 응답을 반환하고 실제 비즈니스 로직은 Job Queue로 위임하는 비동기 처리 구조 설계
• Exponential Backoff 전략을 적용한 재시도 메커니즘 구축으로 일시적 장애 대응력 강화
• source와 eventId를 복합 키로 사용하는 Generic Webhook Receiver 패턴 도입으로 다중 플랫폼 확장성 확보
• 로컬 개발 환경에서 Stripe CLI 및 ngrok을 활용한 이벤트 포워딩 및 테스트 파이프라인 구축

Impact

• 응답 속도 3초 미만 유지로 타임아웃 및 불필요한 재전송 방지
• Webhook 처리 에러율 1% 초과 시 알림 체계 구축
• 디버깅을 위한 원본 페이로드 30일 보관 정책 적용

Key Takeaway

외부 시스템과의 이벤트 연동 시 신뢰할 수 없는 데이터 수신을 전제로 하며, '검증-저장-비동기 처리'의 단계를 분리하여 시스템 안정성을 확보하는 설계 원칙이 중요함.