Webhook으로 수신 이메일 받기

받은편지함을 폴링해도 동작은 하지만, 지연을 더하고 요청을 낭비합니다. Webhook은 모델을 뒤집습니다. '메일 왔어?'를 반복해서 묻는 대신, 메시지가 도착하는 순간 서비스가 여러분에게 연락합니다. 이 글에서는 MoeMail의 API로 수신 이메일 webhook이 어떻게 동작하는지, 그리고 이를 안정적으로 처리하는 법을 다룹니다.

폴링 vs webhook

폴링은 무언가 나타날 때까지 메시지 엔드포인트를 거듭 두드립니다. 간단하지만 느리고 할당량을 많이 먹습니다. webhook은 어떤 이벤트(여기서는 새 수신 이메일)가 일어날 때 제공자가 POST하는, 여러분 소유의 URL입니다. 여러분의 엔드포인트는 반복문 없이 즉시 반응합니다.

작동 방식

여러분이 제어하는 webhook URL을 등록합니다(백엔드 경로나, 테스트 하니스가 노출하는 엔드포인트).
임시 메일함에 메일이 도착하면 MoeMail이 그 메시지 페이로드를 해당 URL로 POST합니다.
핸들러가 요청을 검증하고, 이메일을 분석하고, 행동합니다. 저장하거나, 대기 중인 테스트 단계를 해소하거나, 후속 로직을 유발합니다.

빠르게 응답하세요 — 아니면 재시도됩니다

webhook 핸들러는 몇 초 안에 2xx 상태로 빠르게 응답해야 합니다. 2xx가 아니거나 느린 핸들러는 실패로 간주되어 재시도되므로, 굼뜬 핸들러는 같은 이벤트를 여러 번 받을 수 있습니다. 그래서 두 가지 원칙이 따라옵니다. 핸들러를 가볍게 유지하고(무거운 DB 작업을 인라인으로 하지 말고 큐에 넣으세요), 중복 전달이 무해하도록 처리를 멱등하게 만드세요.

페이로드를 검증하세요

webhook URL은 사실상 공개되어 있으므로, 신뢰하기 전에 요청이 정말 MoeMail에서 왔는지 확인하세요. 계정이 설정한 서명이나 공유 비밀 값을 검증하고, 예상치 못한 형식은 무시하며, 검증되지 않은 입력으로는 절대 행동하지 마세요.

테스트에서의 webhook

이메일 인증 테스트 자동화에서 webhook은 폴링을 완전히 없앱니다. 테스트는 webhook이 발사될 때 해소되는 프로미스를 기다린 뒤, 링크나 코드를 추출합니다. 폴링 반복문보다 훨씬 빠르고 덜 불안정합니다.

시작하기

webhook 페이로드 형식은 OpenAPI 문서에서 확인하고, URL을 핸들러로 향하게 한 뒤, 메일함을 만들어 자신에게 테스트 메시지를 보내 보세요.