Payment Webhook Doctor
증거부터 시작하세요, 재전송이 아닙니다. 손상된 핸들러에 이벤트를 다시 보내면 부작용이 반복될 수 있습니다.
한 번에 하나의 작업 경로
| 문제 | 참고 문서 |
|---|---|
| 서명 실패, 잘못된 시크릿, 파싱된 본문, 오래된 전달 | references/signatures.md |
| 중복 크레딧, 지연된 이행, 성공 후 실패, 순서가 잘못된 환불 | references/reconciliation.md |
| 4xx/5xx/타임아웃, 복구, 누락된 이벤트, 프로덕션 배포 | references/incident-playbook.md |
| 검증된 프로토콜 사실과 버전 경계 필요 | references/sources.md |
| Stripe 이외 / M-Pesa 어댑터 필요 | references/provider-boundary.md |
워크플로우
- 범위 설정: 제공업체, 스냅샷 대 thin 이벤트, 테스트/라이브 모드, 연결된 계정, 엔드포인트 프레임워크 및 API 버전. 진단을 변경하는 누락된 사실만 질문하세요.
- 핸들러 코드, 마이그레이션, 예상 주문 금액/통화, 서버 생성 PaymentIntent 매핑, 수정된 전송 메타데이터를 검사하세요. 서명 시크릿은 로컬 환경 변수에 보관하세요. 사용자에게 시크릿이나 고객 본문을 채팅에 붙여넣도록 요청하지 마세요.
- JSON을 파싱하기 전에 정확한 원시 요청 바이트를 검증하세요. 배포된 핸들러에는 공식 Stripe SDK를 선호하세요. 번들된 의존성 없는 검증기는 대체 SDK가 아닌 작고 검사 가능한 진단 참조 도구입니다.
- 아래 로컬 도구를 사용하여 합성 픽스처로 먼저 결함을 재현하세요. 증거를 관찰됨, 추론됨, 또는 미검증됨으로 분류하세요. 유효한 서명은 전달을 인증할 뿐, 주문이 이행되어야 함을 증명하지 않습니다.
- 가장 작은 원인을 수정하고 회귀 테스트를 추가하세요. 결제를 신뢰할 수 있는 서버 측 주문에 바인딩하고, 금액, 통화, 계정 범위 및 모드를 비교하세요. 받은 편지함, 원장 업데이트 및 부작용 의도를 하나의 데이터베이스 트랜잭션에 유지하세요.
- 중복, 동일 객체에 대한 별개 이벤트, 재시작, 순서가 잘못된 전달, 실패한 이벤트, 부분/전체 환불을 검증하세요. 이벤트 타임스탬프를 전체 순서 결정 메커니즘으로 사용하지 마세요.
- 결과, 패치, 테스트 증거, 해결되지 않은 통합 요구사항, 명시적인 롤백/복구 계획을 전달하세요. 사용자의 승인된 워크플로우 없이 라이브 이벤트를 배포하거나 재전송하거나, 환불을 발행하거나, 자금을 이체하지 마세요.
로컬 도구
이 스킬의 루트에서 실행하세요:
npm test
npm run demo
문서화된 픽스처 시계를 사용하여 저장된 테스트 모드 픽스처를 검사하세요:
export DOCTOR_FIXTURE_SECRET='fixture_only_not_a_live_secret'
node scripts/doctor.mjs --body fixtures/payment.json --header fixtures/signature.txt \
--secret-env DOCTOR_FIXTURE_SECRET --fixture-now 1794130000 \
--normalized-out /tmp/payment-doctor-event.json
python3 scripts/ledger.py --db /tmp/payment-doctor-reference.sqlite \
--orders fixtures/orders.json < /tmp/payment-doctor-event.json
내보내기는 기존 파일을 덮어쓰지 않습니다. 새 출력 경로를 사용하거나 의도적으로 합성 출력을 직접 제거하세요. Python CLI는 명시적으로 지정된 로컬 SQLite 데이터베이스에만 기록합니다. 검증기의 신뢰할 수 있는 정규화된 출력을 기대하며, 자체적으로 서명을 검증하지 않습니다. 공개 웹훅 엔드포인트로 절대 노출하지 마세요.
일반 진단 보고서는 고객 데이터, 원시 페이로드 및 서명을 제외합니다. 명시적인 정규화된 내보내기는 로컬 조정에 필요한 식별자와 정수 금액을 유지합니다. 비공개로 유지하고 버전 관리에서 제외하세요.
--fixture-now는 오래된 합성 테스트 이벤트 전용이며, 라이브 모드 입력을 거부합니다. 일반적인 현재 전달에서는 생략하세요. 참조 원장은 라이브 모드 이벤트를 거부하고, Stripe를 호출하지 않으며, 아웃박스 행을 전송하지 않습니다.
필수 보고서
- 결과: 발생한 상황과 재현 여부.
- 증거: 파일/라인, 익명화된 전송 메타데이터, 정확한 명령어, 관찰된 결과.
- 근본 원인: 확인된 원인 대 남아있는 가설.
- 수정: 최소 패치 및 마이그레이션/백필 영향.
- 회귀 매트릭스: 중복, 재시작, 범위 불일치, 잘못된 금액/통화, 순서, 환불 사례.
- 운영 인수인계: 여전히 필요한 테스트 모드 통합 증거, 안전한 재전송 및 롤백 기준.
경계
지원 범위는 의도적으로 좁습니다: Stripe 스냅샷 payment_intent.succeeded, payment_intent.payment_failed 및 환불 객체 이벤트. Thin 이벤트, 구독 권한, Checkout 세션, 분쟁, 다중 캡처 결제 의미, 애플리케이션 수수료, 세금 및 Connect 전송은 전용 어댑터가 필요합니다. 결과가 발견되지 않았다고 해서 보안 인증이나 자금 도착 증명이 아닙니다. 확장하기 전에 참조 문서를 확인하세요.