Webhook 보안/재전송/이벤트 식별자 관련 정책 확인 요청
안녕하세요.
토스페이먼츠 PG 연동을 준비 중인 개발자입니다.
Webhook 기반 Confirmed-Only 처리 구조를 설계 중인데,
공식 문서에서 명확하지 않은 부분이 있어 정책 확인을 요청드립니다.
A. Webhook 서명(Signature) 관련
1. 모든 webhook 이벤트에 tosspayments-webhook-signature 헤더가 포함되나요?
문서상 payout.changed / seller.changed 이벤트에만 언급되어 있는데, 결제/취소 계열(PAYMENT_STATUS_CHANGED 등)에도 포함되는지 궁금합니다.
2. 결제/취소 계열 webhook에는 별도의 서명 검증 방식이 존재하나요? 없다면 paymentKey 기반 API 조회 후 confirmed 검증이 공식 권장 방식인지 확인 부탁드립니다.
3. tosspayments-webhook-transmission-time 기반 replay 공격 방어를 구현하려고 하는데, 공식적으로 권장되는 timestamp 유효 시간(예: ±5분 등)이 존재하나요?
B. Webhook 재전송 정책 관련
1. webhook 재전송 시
- tosspayments-webhook-transmission-id는 동일하게 유지되나요?
- payout/seller 이벤트의 eventId도 동일하게 유지되나요?
2. 테스트 모드와 라이브 모드에서 재전송 정책(횟수/간격/동작)이 동일한가요?
3. 공식적으로 “webhook 중복 전송을 정상 동작으로 가정하고 멱등 처리하라”는 권장 정책이 있는지 궁금합니다.
C. 결제/취소 식별자 관련
1. paymentKey는 전역 유니크 값으로 이해하면 되는지 확인 부탁드립니다.
2. 부분취소가 여러 번 발생하는 경우:
- 각 취소는 transactionKey로 고유하게 식별되는 것이 맞는지요?
- 동일 취소에 대한 webhook 재전송 시 transactionKey는 동일하게 유지되나요?
D. 금액 비교 기준 관련
결제 성공 시 금액 정합성 검증을 위해 payment.totalAmount를 최초 요청 금액과 직접 비교하려고 합니다.
1. 결제 확정 금액 비교 기준 필드는 totalAmount가 맞는지요?
2. 부분취소 시 개별 취소 금액은 cancels[].cancelAmount가 정확한 기준인지 확인 부탁드립니다.
운영 설계상 멱등성/중복처리/금액정합성 기준을 고정하기 위함이니
가능하면 정책 기준으로 답변 주시면 감사하겠습니다.
감사합니다.
토스페이먼츠 PG 연동을 준비 중인 개발자입니다.
Webhook 기반 Confirmed-Only 처리 구조를 설계 중인데,
공식 문서에서 명확하지 않은 부분이 있어 정책 확인을 요청드립니다.
A. Webhook 서명(Signature) 관련
1. 모든 webhook 이벤트에 tosspayments-webhook-signature 헤더가 포함되나요?
문서상 payout.changed / seller.changed 이벤트에만 언급되어 있는데, 결제/취소 계열(PAYMENT_STATUS_CHANGED 등)에도 포함되는지 궁금합니다.
2. 결제/취소 계열 webhook에는 별도의 서명 검증 방식이 존재하나요? 없다면 paymentKey 기반 API 조회 후 confirmed 검증이 공식 권장 방식인지 확인 부탁드립니다.
3. tosspayments-webhook-transmission-time 기반 replay 공격 방어를 구현하려고 하는데, 공식적으로 권장되는 timestamp 유효 시간(예: ±5분 등)이 존재하나요?
B. Webhook 재전송 정책 관련
1. webhook 재전송 시
- tosspayments-webhook-transmission-id는 동일하게 유지되나요?
- payout/seller 이벤트의 eventId도 동일하게 유지되나요?
2. 테스트 모드와 라이브 모드에서 재전송 정책(횟수/간격/동작)이 동일한가요?
3. 공식적으로 “webhook 중복 전송을 정상 동작으로 가정하고 멱등 처리하라”는 권장 정책이 있는지 궁금합니다.
C. 결제/취소 식별자 관련
1. paymentKey는 전역 유니크 값으로 이해하면 되는지 확인 부탁드립니다.
2. 부분취소가 여러 번 발생하는 경우:
- 각 취소는 transactionKey로 고유하게 식별되는 것이 맞는지요?
- 동일 취소에 대한 webhook 재전송 시 transactionKey는 동일하게 유지되나요?
D. 금액 비교 기준 관련
결제 성공 시 금액 정합성 검증을 위해 payment.totalAmount를 최초 요청 금액과 직접 비교하려고 합니다.
1. 결제 확정 금액 비교 기준 필드는 totalAmount가 맞는지요?
2. 부분취소 시 개별 취소 금액은 cancels[].cancelAmount가 정확한 기준인지 확인 부탁드립니다.
운영 설계상 멱등성/중복처리/금액정합성 기준을 고정하기 위함이니
가능하면 정책 기준으로 답변 주시면 감사하겠습니다.
감사합니다.
