웹훅
물어볼 때가 아니라, 일어날 때 알려 드립니다.
https 엔드포인트를 등록하면 메일이 도착하거나, 발송되거나, 반송되거나, 열람될 때 서명된 POST를 받습니다.
한마디로
이메일 웹훅이란?
웹훅은 무언가 일어났을 때 서비스가 지정된 URL로 보내는 HTTP 요청으로, 코드가 폴링하지 않고 바로 반응하게 해 줍니다. 이메일에서는 메일의 도착, 발송, 반송, 열람이 그 대상입니다.
20
구독할 수 있는 이벤트
10
메일함당 엔드포인트
5
이벤트당 최대 시도 횟수
100
연속 실패 시 엔드포인트 비활성화
작동 방식
어떤 발송 방법이든, 하나의 이벤트
편집기, 화요일로 예약한 발송, API 모두 email.sent를 일으킵니다. 예약하면 먼저 email.scheduled가 발생합니다.
서명 포함, 확인은 직접
모든 POST에는 타임스탬프와 원본 본문의 HMAC-SHA-256이 실립니다. 도착한 그대로의 바이트로 확인하고, 300초보다 오래된 것은 거부하세요.
성공할 수 있을 때만 재시도
타임아웃, 408, 425, 429, 5xx는 1분, 5분, 25분 뒤, 그다음 2시간 뒤에 재시도합니다. 그 밖의 4xx는 최종이며, 410은 엔드포인트를 끕니다.
세 계열, 이벤트 20종
아무것도 고르지 않으면 email.replied를 제외한 모든 메시지 이벤트를 구독합니다.
전송 검증하기
SDK는 HMAC을 상수 시간으로 확인하고 5분보다 오래된 전송은 거부합니다.
import { verifyWebhookSignature } from '@openemail/sdk' export default async (request: Request) => { const event = await verifyWebhookSignature({ payload: await request.text(), headers: request.headers, secret: process.env.OPENEMAIL_WEBHOOK_SECRET! }) console.log(event.type, event.data) return new Response(null, { status: 204 })}제공 기능
지금 제품에 있는 것
5초, 병렬로
엔드포인트는 동시에 호출되므로 10개여도 5초면 됩니다.
공개 https만
사설 호스트와 루프백 호스트는 거부되며, 리디렉션은 절대 따라가지 않습니다.
모든 시도를 기록
시도마다 서버가 무엇을 응답했고 얼마나 걸렸는지 보여 줍니다.
활용 팁
제대로 활용하기
- 01
먼저 응답하고, 나중에 처리
5초 안에 2xx를 반환하고, 오래 걸리는 작업은 그 뒤에 하세요.
- 02
중복 id는 버리기
처리한 X-OpenEmail-Delivery id를 모두 저장하고 중복은 건너뛰세요.
- 03
두 시크릿으로 교체
교체하면 시크릿이 즉시 바뀌므로, 배포가 반영될 때까지 이전 시크릿과 새 시크릿 모두로 검증하세요.
질문
자주 묻는 질문
더 보기
