본문으로 건너뛰기

Webhooks Production Checklist

연동을 프로덕션으로 옮기기 전 다음 항목을 점검하세요. 각 항목은 관련된 상세 가이드로 링크되어 있으니, 미흡한 항목은 해당 페이지에서 확인 후 보완하세요.

전송 채널​

  • HTTPS endpoint 사용
  • CROSS Pay 측에 운영용 callback_url 등록 완료 (Overview — callback URL 등록)
  • 방화벽·WAF 가 CROSS Pay 발송 서버 IP 를 차단하지 않음

서명 검증​

  • raw body 보존 (서명 검증 전 JSON 파싱 금지) (Verifying — raw body 보존)
  • HMAC 비교는 constant-time (timingSafeEqual / subtle.ConstantTimeCompare)
  • webhook-timestamp ±5분 검증 (Verifying — Replay 보호)
  • 시크릿 배열로 검증해 향후 다중 시크릿 발송 호환성 확보

멱등성·재시도​

  • webhook-id 기반 dedup 테이블 운영 (Delivery — 멱등성 / 중복 처리)
  • 응답 ≤ 10초 (무거운 처리는 큐로 위임) (Delivery — 재시도 정책)
  • 2xx 와 409 외 모든 응답 코드는 재시도 유발 — 명시적 4xx/5xx 사용 신중히 (중복 dedup 결과는 200 또는 409 로 응답)
  • 도메인 처리는 dedup 트랜잭션과 같은 트랜잭션 안에서

보안·로깅​

  • 시크릿은 시크릿 매니저 또는 환경변수에 보관, 코드 커밋 금지 (Overview — 시크릿)
  • 서명·시크릿은 로그에 남기지 않거나 마스킹
  • webhook 본문은 PII 가 있을 수 있으므로 로그 보존 정책 검토
  • 401·5xx 응답이 일정 비율 초과하면 알람

비즈니스 로직​

  • 브라우저 결과 단독으로 주문을 확정하지 않음 (popup result / redirect param 만으로 결제 확정 금지)
  • terminal 상태(PAID/FAILED/EXPIRED/CANCELLED) 도달 후 새 결제는 반드시 새 POST /v1/payments 호출로 시작
  • payment.completed 페이로드에 fee breakdown 이 없으므로, 정산이 필요하면 GET /v1/payments/:id 로 보강 조회
  • failure_reason 의 알 수 없는 값은 UNKNOWN 으로 fallback 처리
  • provider 값(binancepay / payletter / onchain) 에 비즈니스 로직을 직접 의존하지 않음 — status·금액 기준으로 판단

운영 모니터링​

  • 수신율·서명 검증 실패율·중복률·처리 지연(p95) 대시보드
  • webhook 처리 지연 알람 (예: p95 > 5s)
  • webhook 처리 실패 알람 (5xx 비율 > N%)
  • failure_reason=ONCHAIN_TIMEOUT 비율 추적 (네트워크 이상 시 급증 가능)

다음 단계​

문제가 발생하거나 더 깊은 내용이 필요하면: