전달 신뢰성 (재시도 · 멱등 · 순서)

성공 판정 — 2xx 필수

여러분의 웹훅이 2xx 를 반환해야 전달이 성공으로 간주됩니다. 그 외(4xx·5xx·타임아웃·네트워크 오류)는 모두 재시도됩니다.

경고

4xx도 재시도 대상입니다. 요청을 정상 수신·처리했다면 반드시 2xx를 돌려주세요 — 아니면 같은 이벤트가 계속 재전송됩니다.

재시도 정책

아래 정책은 호스티드 게이트웨이(톡브릿지 센터) 기준입니다.

• 전달 방식: at-least-once(최소 1회 이상 — 중복 가능).
• 백오프: 1s → 5s → 30s → 2m → 10m, 총 5회 시도.
• 게이트웨이는 전달 원장을 영속하므로, 게이트웨이 재기동 후에도 미완료 전달을 재개합니다.
• 5회 모두 실패하면 해당 전달은 Failed로 표시되고 게이트웨이 상태가 Degraded로 보고됩니다(전체 동작은 계속).

CLI 릴레이는 경량 재시도

CLI 게이트웨이의 웹훅 릴레이는 인메모리 경량 재시도입니다 — 일시적 실패 시 1s → 3s 백오프로 최대 3회 시도하며 영속 재개는 하지 않습니다(프로세스가 살아 있는 동안만). 재시도 간 X-Bridge-Delivery-Id는 동일하므로 수신측 멱등 처리는 동일하게 적용하면 됩니다. → CLI 게이트웨이

멱등 처리

같은 이벤트를 두 번 이상 받을 수 있으므로 멱등하게 처리하세요.

중복 제거 키	용도
X-Bridge-Delivery-Id	재시도 중복 제거 — 같은 전달의 재시도는 동일 ID
(brand, seq)	논리 이벤트 유일성 — 저널 시퀀스 기준

권장: X-Bridge-Delivery-Id 를 우선 키로 저장해 이미 처리한 전달을 건너뛰세요.

seq 재사용 주의

저널이 리셋되면 seq가 재사용될 수 있습니다. 장기 멱등 저장은 Delivery-Id 기준이 더 안전합니다.

순서

• 게이트웨이는 브랜드 내 전송 순서를 보존하려 하지만, 재시도가 끼면 도착 순서가 뒤바뀔 수 있습니다.
• 순서가 중요하면 payload의 seq로 재정렬하세요(단조증가).

체크리스트

• 서명 검증 실패 → 401(재시도돼도 계속 실패하도록)
• 정상 처리 → 2xx
• Delivery-Id로 중복 스킵
• kind: "agent" echo 필터
• 처리 지연 시에도 빠르게 2xx 응답하고 비동기로 후처리(게이트웨이 타임아웃 회피)