이벤트 및 웹훅
웹훅 연결
통합 설정에서 웹훅을 수신할 주소를 지정하세요. 새 편지, 사서함 상태 및 작업 결과에 대한 알림을 받게 됩니다.
통합 설정에서 별도의 웹훅 비밀을 설정하고 전달을 활성화하세요. 이 비밀은 알림 서명을 확인하는 데 사용됩니다. 메일 API-key는 이에 적합하지 않습니다.
알림 형식
알림은 Content-Type: application/json. 필드 event와 함께 HTTP POST- 요청에 이벤트 유형 timestamp — 알림 시간, data — 이벤트 데이터를 포함합니다. data의 구성은 이벤트에 따라 다릅니다.
식별자 data.event_id을 사용하면 재배송을 인식할 수 있습니다. 통합 ID와 함께 저장하고 하나의 이벤트를 한 번만 처리하세요.
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}확인 및 확인
헤더 X-Webhook-Signature에는 소문자 16진수 표기법으로 HMAC-SHA256이 포함되어 있습니다. 요청 본문의 원본 바이트와 웹훅 비밀에서 서명을 계산합니다. 데이터를 처리하기 전에 서명을 확인하세요. JSON을 다시 직렬화하면 서명되는 바이트가 변경됩니다.
서명을 확인하고 이벤트를 저장한 후 HTTP 200 또는 201을 반환합니다. 응답 202 및 204는 수신을 확인하지 않습니다. 10초 이내에 답변하세요. 이벤트를 저장한 후 시간이 오래 걸리는 처리를 수행하십시오.
알림은 반복적으로 또는 순서 없이 도착할 수 있습니다. 구독 상태를 변경하기 전에 현재 세부 정보를 확인하세요. 통합 설정에서 배송 내역을 확인할 수 있습니다.
어떤 이벤트가 발생하나요?
mailbox.created- 상자가 생성되어 사용할 준비가 되었습니다.
mailbox.expiring- 박스 유료기간 종료가 다가오고 있습니다.
mailbox.renewed- 박스 유료 기간이 연장되었습니다.
mailbox.suspended- 사서함에 대한 액세스가 일시 중지되어 읽기 및 보내기가 불가능합니다.
mailbox.resumed- 사서함에 대한 액세스가 복원되었습니다.
mailbox.deleting_soon- 미납박스 삭제까지 1시간 남았습니다.
mailbox.deleted- 상자가 삭제되었습니다.
mailbox.account_changed- 사서함이 다른 메일 계정에 연결되어 있습니다.
mail.message.received- 새로운 편지가 우편함에 나타났습니다.
mail.operation.succeeded- 작업이 성공적으로 완료되었습니다. 발송의 경우 이는 수신자의 받은 편지함으로 배달되는 것이 아니라 메일 서버에서 편지를 수락하는 것을 의미합니다.
mail.operation.failed- 작업이 실패했습니다.
mail.operation.uncertain- 전송 결과를 알 수 없습니다. 다시 보내기 전에 상태를 확인하십시오.
결제 알림: 만료 14, 7, 3, 2, 1일 및 1시간 전. 갱신하면 아직 전송되지 않은 오래된 알림이 취소됩니다.