Resend 웹훅은 어떻게 동작하나요?

Resend 웹훅 워크플로

공개 HTTPS 엔드포인트를 만들고, 애플리케이션에 필요한 이벤트 유형과 함께 Resend에 등록하면 워크플로가 시작됩니다. 일치하는 이벤트가 발생하면 Resend는 JSON 페이로드가 담긴 POST 요청을 보냅니다. 페이로드에는 email.sent, email.delivered, email.bounced, email.complained 같은 type, 생성 시각, 이벤트별 데이터가 들어 있습니다. 모든 페이로드의 형태가 같다고 가정하지 말고 type 필드에 따라 처리 경로를 나누세요.

처리하기 전에 요청 검증하기

요청을 원본 텍스트로 읽고, 웹훅 서명 시크릿과 svix-id, svix-timestamp, svix-signature 헤더로 검증하세요. 페이로드를 파싱하거나 그에 따라 동작하기 전에 이 검증을 먼저 수행하세요. JSON을 파싱한 뒤 다시 직렬화하면 바이트가 바뀌어 정상적인 서명도 실패할 수 있습니다. 검증을 통과하지 못한 요청은 거부하고, 서명 시크릿은 소스 코드가 아니라 시크릿 관리자나 보호된 환경 변수에 보관하세요.

이벤트 처리를 멱등하게 만들기

Resend는 최소 한 번 전달(at-least-once)을 문서화하고 있으므로 같은 이벤트가 엔드포인트에 두 번 이상 도착할 수 있습니다. svix-id를 고유 제약 조건과 함께 저장하고, 이미 처리한 식별자라면 비즈니스 로직을 건너뛰세요. 도착 순서에도 의존하지 마세요. 재시도와 네트워크 지연으로 이벤트 순서가 바뀔 수 있습니다. 순서가 중요할 때는 이벤트의 created_at 값을 사용하고, 오래된 이벤트가 최신 상태를 실수로 덮어쓰지 않도록 상태 변경을 설계하세요.

빠르게 응답하고 안전하게 처리하기

이벤트를 검증하고 안정적으로 기록한 후에 HTTP 200을 반환하고, 더 오래 걸리는 작업은 큐나 백그라운드 워커로 수행하세요. 타임아웃이나 성공이 아닌 응답이 나오면 전달이 다시 시도되므로, 동기식 핸들러가 길어지면 피할 수 있는 중복이 생깁니다. 발송 제외 레코드 업데이트, 지원팀 알림, 반송 기록 같은 부수 효과와 수집 단계를 분리하세요. 각 부수 효과 역시 반복해도 안전하거나 저장된 이벤트 식별자로 보호되어야 합니다.

재시도, 리플레이, 장애 복구 테스트하기

프로덕션에 배포하기 전에 잘못된 서명, 중복 식별자, 순서가 뒤바뀐 타임스탬프, 일시적인 데이터베이스 장애를 포함해 대표적인 이벤트 유형으로 엔드포인트를 테스트하세요. Resend는 실패한 전달을 백오프 일정에 따라 재시도하며, 실패한 웹훅 메시지와 성공한 웹훅 메시지를 모두 리플레이할 수 있게 해 줍니다. 리플레이는 장애 후 복구하거나 업데이트한 핸들러 코드를 검증할 때 사용하되, 복구 과정에서 고객에게 보이는 부수 효과가 반복되지 않도록 중복 제거를 계속 활성화해 두세요.

팀에서 자주 묻는 질문

1차 출처

• 웹훅 관리 — Resend
• 웹훅 요청 검증 — Resend
• 재시도와 리플레이 — Resend
• 웹훅 이벤트 유형 — Resend