Webhook과 상태 전이

이 문서는 Billing Authority의 webhook·상태 전이를 구현·운영하는 개발자를 위한 참고입니다. 이 서비스를 채택한 제품은 중복 webhook handler를 만들지 않습니다. 제품 소유 결제 실행 구조에서는 승인된 제품 서버가 webhook 검증과 상태 전이를 소유합니다(아키텍처 경계).

수신과 적용을 분리합니다

HTTP receive
  → raw event persist
  → transmission/event id claim
  → provider verification or re-query
  → normalized evidence
  → allowed local transition
  → catalog grant resolution
  → entitlement transition
  → audit record

HTTP 200 응답 여부와 도메인 처리 완료 여부는 같은 상태가 아닙니다. 재전송을 고려해 원문 저장과 멱등 claim이 먼저 이루어져야 합니다.

멱등성

• provider transmission ID 또는 provider event ID에 unique constraint를 둡니다.
• 같은 event가 반복되면 기존 처리 결과를 반환하고 상태 전이를 다시 만들지 않습니다.
• product mutation은 Leysys account, operation, idempotency key 범위에서 중복을 차단합니다.
• 원문 hash와 수신 시각, 처리 시도, 결과, 오류 분류를 감사 기록에 연결합니다.
• timeout 뒤 새 payment attempt를 만들기 전에 기존 provider identifier로 조회합니다.

공급자별 검증 경계

각 adapter는 실제 사용하는 공급자의 공식 계약에 따라 webhook을 검증합니다. 서명·이벤트 식별자·거래 재조회 방식은 공급자와 event type별로 확인하며, 공식 계약에 없는 헤더나 필드를 가정하지 않습니다.

전송·이벤트 ID의 멱등 claim과 원문 보존 후, 공식 계약에 따른 서명 검증·서버 거래 재조회로 근거를 확인합니다. 공급자 거래 식별자와 로컬 checkout/payment의 주문·금액·상태를 대조하고, 검증되지 않은 webhook 원문만으로 결제나 이용 권한을 확정하지 않습니다.

상태 모델 원칙

상태	의미	허용 행동
pending	처리 시작 전 또는 외부 결과 대기	동일 operation 조회·처리 재개
succeeded	검증된 성공과 로컬 commit 완료	멱등 결과 반환
failed	provider 또는 정책상 확정 실패	오류 분류에 따른 사용자 조치
unknown	timeout·응답 소실 등으로 결과 불명확	같은 provider에서 reconciliation
canceled	checkout/구독 취소가 확정됨	정책에 따른 entitlement 종료
refunded / partially_refunded	환불 사실이 확정됨	catalog 정책에 따른 entitlement 재계산

상태 이름의 실제 enum과 허용 전이 표는 runtime schema가 정본입니다. 이 표는 제품이 provider 상태를 직접 매핑하라는 뜻이 아닙니다.

보안과 보존

provider event 원문에는 개인정보와 결제정보가 포함될 수 있습니다. service-role만 접근하고 제품 API와 관리자 UI에 그대로 노출하지 않습니다. 보존 기간·파기·마스킹·접근 감사는 운영 승인 전에 확정해야 합니다.

공식 참고

adapter를 변경할 때는 공급자 공식 문서에서 실제 사용하는 공급자의 검증 계약을 확인하십시오. 공급자별 필드와 이벤트는 adapter 내부에서 해석하고 제품에는 정규화된 계약을 제공합니다.