Developers·2026-04-01·6 분 분량
모든 결제 webhook에는 세 가지 보장이 필요합니다: 진위성(요청이 정말 우리에게서 왔음), at-least-once 전달(이벤트가 조용히 사라지지 않음), 멱등성(재전달이 DB를 이중 청구하지 않음).
진위성: 모든 Baynoy webhook은 X-Baynoy-Signature 헤더를 전송합니다 — 엔드포인트 시크릿으로 sha256(timestamp + '.' + body). 타임스탬프가 5분보다 오래되었거나(재생 방어) 서명이 상수 시간 비교에서 일치하지 않으면 거부. Stripe가 사용하는 정확한 형식을 따르므로 기존 Stripe 검증 미들웨어가 변경 없이 적용됩니다.
At-least-once: 1m, 5m, 30m, 2h, 12h, 24h에서 지수 백오프로 재시도 — 6회 시도로 제한. 각 시도는 응답 상태와 함께 baynoy_webhook_deliveries에 행을 씁니다. 대시보드의 replay-from-UI 버튼은 동일한 delivery 파이프라인을 사용; 특별한 경로 없음.
멱등성: 모든 이벤트는 event.id를 가집니다(UUIDv7 — 정렬 가능, 단조 증가). 첫 수신 시 영구 저장하고 unique constraint로 DB 수준에서 중복을 거부하세요. 우리는 재전달할 것입니다. 제약 조건이 당신의 안전망입니다.
미들웨어 세 줄이면 단 하나의 결제 알림도 잃지 않고 6시간 중단을 견디는 webhook 핸들러를 갖게 됩니다.