Idempotency 확보를 통한 At-least-once Webhook 시스템 설계

Build a video webhook handler that survives duplicates (Express + Postgres)

Mason K2026년 6월 15일8분intermediate

AI 요약

Context

비동기 비디오 인코딩 이벤트 처리 시 중복 수신 및 서명 검증 실패로 인한 데이터 유실 위험 존재. 특히 전역 미들웨어의 JSON 파싱으로 인한 Raw Body 훼손과 중복 이벤트에 따른 비즈니스 로직 중복 실행이 주요 병목 지점으로 작용.

전역 express.json() 적용 전 특정 경로에 express.raw()를 배치하여 서명 검증용 원본 바이트 보존
crypto.timingSafeEqual을 활용한 Constant Time 비교로 타이밍 공격 기반의 Secret 유출 방지
Postgres의 UNIQUE Index와 ON CONFLICT DO NOTHING 구문을 활용한 Event-level Idempotency 구현
수신 즉시 DB 영속화 후 200 OK 응답을 반환하는 Fast Ack 구조로 Provider의 불필요한 Retry 방지
비즈니스 로직을 Queue 기반 비동기 워커로 분리하여 Poison Message로 인한 시스템 가용성 저하 차단
Periodic Reconciliation Job을 통한 Webhook 유실 가능성에 대비한 최종 정합성 보장 설계

실천 포인트

1. 서명 검증이 필요한 엔드포인트는 JSON 파싱 전 Raw Body를 확보했는지 확인

2. At-least-once 메시징 시스템에서 고유 ID 기반의 Unique Constraint를 통한 중복 제거 로직 적용

3. 비즈니스 에러 시 500 응답 대신 200 응답 후 DLQ(Dead Letter Queue)에서 처리하는 전략 검토

4. 외부 API 의존 시 Webhook 외에 폴링 기반의 데이터 대조(Reconciliation) 프로세스 구축

태그