실패한 웹훅을 버리지 않는 재처리 대기열 설계

웹훅 수신에 실패한 이벤트를 몇 번 재시도한 뒤 조용히 버리면 데이터가 어긋납니다. 실패한 이벤트가 어디에 있고 누가 언제 다시 처리할지 보이는 재처리 대기열이 필요합니다.

실패 유형을 먼저 나눈다

일시적 네트워크 오류와 상대 시스템의 과부하는 재시도로 회복될 수 있습니다. 반면 잘못된 형식, 권한 오류, 삭제된 대상은 같은 요청을 반복해도 해결되지 않습니다. 오류 코드와 원인을 기록해 경로를 나눕니다. 수신 측이 응답을 보내기 전에 실제 업무 처리는 끝났을 수도 있으므로, 타임아웃을 단순 실패로 보지 않고 중복 실행 가능성을 같이 확인해야 합니다. 동일 이벤트 ID로 이미 반영됐는지를 조회하는 절차가 필요합니다.

재시도는 제한과 간격을 둔다

즉시 무한 반복하면 장애 중인 상대 시스템을 더 압박합니다. 지수 백오프와 상한, 필요하면 무작위 지연을 두고 마지막 실패 뒤 데드 레터 큐로 이동합니다. 이벤트 원본과 마지막 오류를 함께 보관합니다.

데드 레터 큐는 쓰레기통이 아니다

큐에 쌓인 이벤트를 원인별로 분류하고 담당자를 정해야 합니다. 인증 키 갱신, 데이터 수정, 수신 시스템 복구 후 재처리할 수 있도록 검색·재전송 도구를 제공해야 합니다.

재처리도 멱등해야 한다

같은 이벤트가 자동 재시도와 수동 재처리로 두 번 들어올 수 있습니다. 이벤트 ID와 업무 키로 중복 적용을 막고, 순서 의존성이 있다면 관련 이벤트의 선후를 확인한 뒤 재생합니다.

유실과 지연을 계측한다

성공률만으로는 오래 묶인 이벤트를 찾지 못합니다. 데드 레터 큐 길이, 가장 오래된 이벤트 나이, 재처리 성공률, 실제 데이터 불일치 건수를 함께 봅니다.

현장에 적용할 때의 순서

1. 웹훅 실패를 일시·영구 오류로 분류
2. 횟수 제한 재시도 후 DLQ로 이동
3. 원인 수정 뒤 멱등 재처리

주의할 실패: DLQ에 넣으면 운영이 끝났다고 생각

관찰할 지표: DLQ 최장 대기·재처리 성공률·유실 건수

적용 전 체크리스트

• 재시도 가능 오류와 영구 오류를 구분한다
• DLQ에 원본 이벤트 ID·오류·시각을 남긴다
• 재처리 후 중복·순서·데이터 일치 여부를 확인한다

참고 자료

RabbitMQ — Dead Letter Exchanges. 데드 레터 교환기의 동작 개념은 RabbitMQ 공식 문서를 참고했습니다. 웹훅 재처리 정책은 애플리케이션 요구에 맞춘 설계 예시입니다.

이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.

#웹훅 #Webhook #DLQ #데드레터큐 #재시도 #멱등성 #이벤트처리 #비동기 #운영 #장애대응