재시도 및 멱등성

전송과 재시도

엔드포인트가 10초 안에 HTTP 2xx 로 응답하면 전송 성공으로 간주됩니다. 그 외 (타임아웃, 4xx, 5xx, 네트워크 오류) 는 모두 재시도를 트리거합니다.

재시도 스케줄

ParaSta 는 3일에 걸쳐 최대 24회 지수 백오프로 재시도합니다. 전체 스케줄:

시도	후
1	1분
2	5분
3	30분
4	1시간
5	6시간
6	12시간
7+	24시간씩 (총 24회까지)

마지막 시도 후 이벤트는 delivery_failed 로 표시되며 재시도가 중단됩니다. 대시보드에서 수동 재전송이 가능합니다.

수신 측 멱등성

재시도 때문에 동일 이벤트가 여러 번 전달될 수 있습니다. 항상 event.id 로 중복 제거하세요.

const seen = await db.webhookEvents.findUnique({ where: { id: event.id } });
if (seen) return res.json({ received: true });
await db.webhookEvents.create({ data: { id: event.id, ... } });
// ...처리

저장소에서 event.id 를 unique 제약으로 다루세요. 멱등성 윈도우는 최소 3일 재시도 윈도우 — 안전하게 7일 이상 보관하세요.

송신 측 멱등성 (Idempotency-Key)

ParaSta 로 보내는 outbound POST 요청 (Payment, Checkout Session, Refund 생성) 에는 Idempotency-Key 헤더를 포함하세요. ParaSta 는 24시간 동안 응답을 캐시하며, 동일 키 + 동일 본문의 후속 요청은 캐시된 응답을 반환합니다. 동일 키 + 다른 본문은 409 idempotency_error 를 반환합니다.

Idempotency-Key: order_4567_create_payment

본인 측 재시도가 중복 Payment 를 만들지 않도록 안정적인 키 (내부 주문 ID 등) 를 사용하세요.