웹훅 설정

게시일: 2026년 7월 16일 · 최종 업데이트: 2026년 9월 12일 · 작성자 Marcus Biel

핵심 요약

Maildroppa 웹훅 엔드포인트 생성부터 이벤트 선택, 보안 헤더 추가, 서명 검증, 전송 테스트, 재시도 내역 확인, 이벤트 재전송까지 설정과 관리 방법을 알아보세요.

웹훅을 사용하면 계정에서 중요한 이벤트가 발생했을 때 Maildroppa가 다른 애플리케이션에 알림을 보낼 수 있습니다.

구독자가 생성되거나 정보가 수정되었는지, 구독을 해지했는지, 태그가 할당되었는지를 Maildroppa에 반복해서 조회할 필요가 없습니다. 이벤트가 발생하면 잠시 후 애플리케이션에서 HTTPS 요청을 받을 수 있습니다.

Webhooks 페이지에서는 계정 전체에 적용되는 이 연동 기능을 한곳에서 관리할 수 있습니다. 여러 엔드포인트를 만들고, 각 엔드포인트에서 받을 이벤트를 선택하고, 인증 헤더를 추가할 수 있습니다. 연결 테스트, 전송 시도 내역 확인, 필요한 경우 프로덕션 이벤트 재전송도 가능합니다.

웹훅: Webhooks 페이지 전체 화면

계정 웹훅의 작동 방식

계정 웹훅은 다음 순서로 작동합니다.

구독자 생성과 같은 이벤트가 Maildroppa에서 발생합니다.
Maildroppa가 해당 이벤트를 구독하는 모든 활성 엔드포인트를 찾습니다.
조건에 맞는 각 엔드포인트에 대해 전송 건을 하나씩 생성합니다.
계정의 웹훅 서명 시크릿(Signing secret)으로 JSON 페이로드에 서명합니다.
저장된 엔드포인트 URL로 HTTPS POST 요청을 보냅니다.
엔드포인트가 서명을 검증하고 이벤트를 저장하거나 처리한 다음 HTTP 응답을 반환합니다.
Maildroppa가 전송 기록(Delivery history)에 결과를 기록하고, 일시적인 오류가 발생하면 자동으로 재시도합니다.

여러 엔드포인트가 같은 이벤트를 구독하면 각 엔드포인트에 개별적으로 전송됩니다. 이때 비즈니스 이벤트를 식별하는 Event ID는 모두 같지만, 각 전송 건에는 고유한 Delivery ID가 부여됩니다.

계정 웹훅은 자동화 내의 “Send a webhook” 단계와 다릅니다. 계정 웹훅은 Maildroppa 전반에서 선택한 계정 이벤트를 감지합니다. 반면 자동화 웹훅은 구독자가 해당 단계에 도달했을 때만 전송됩니다. 두 기능 모두 계정의 웹훅 Signing secret을 사용하므로, 시크릿을 교체하면 Maildroppa 서명을 검증하는 모든 발신 웹훅 수신기에 영향을 줍니다.

Webhooks 페이지 열기

“Settings”를 열고 “Developers”를 펼친 다음 “Webhooks”를 선택하세요.

페이지는 다음 세 가지 주요 영역으로 구성됩니다.

Signing secret: 서명 시크릿
Endpoints: 엔드포인트
Delivery history: 선택한 엔드포인트의 전송 기록

엔드포인트가 여러 개라면 원하는 엔드포인트 행을 선택해 전송 기록을 확인하세요. 별도로 선택하지 않으면 Maildroppa는 목록의 첫 번째 엔드포인트 기록을 표시합니다.

엔드포인트 생성 전 준비 사항

Maildroppa를 설정하기 전에 서버에 수신기를 준비하세요. 수신기는 다음 조건을 충족해야 합니다.

공개 HTTPS URL로 접근할 수 있어야 합니다.
application/json 본문을 포함하는 POST 요청을 수락해야 합니다.
Maildroppa 서명 검증이 끝날 때까지 원시 요청 본문을 그대로 보존해야 합니다.
이벤트를 안전하게 수락한 후에만 2xx 상태를 반환해야 합니다.
Event ID를 사용해 반복 전송을 멱등적으로 처리해야 합니다.
요청 처리 중에 시간이 오래 걸리는 작업을 수행하지 않고 신속하게 응답해야 합니다.

안정적인 처리 방식은 요청을 검증하고, Event ID와 페이로드를 영속성 큐 또는 데이터베이스에 저장한 다음 200 또는 204를 반환하고, 이후에 비즈니스 작업을 처리하는 것입니다.

개발용 컴퓨터, 로컬 네트워크 주소 또는 보호되지 않은 스크립트를 프로덕션 웹훅 수신기로 외부에 노출하지 마세요. Maildroppa는 공개 HTTPS 대상만 허용하며, 전송 시 대상의 유효성을 다시 확인합니다.

1단계: Signing secret 생성

모든 Maildroppa 웹훅 요청에는 서명이 포함됩니다. 수신기는 Signing secret을 사용해 요청이 Maildroppa에서 생성되었고 전송 중 본문이 변경되지 않았는지 검증합니다.

페이지 상단의 Signing secret 패널에는 다음 상태 중 하나가 표시됩니다.

Missing — 아직 Signing secret이 없습니다.
Ready — Signing secret이 설정되어 있습니다.
Loading — Maildroppa가 현재 상태를 불러오는 중입니다.

상태가 Missing이면 “Generate secret”을 클릭하세요.

Maildroppa는 새 시크릿을 즉시 표시합니다. 시크릿은 whsec_로 시작합니다. “Copy”를 클릭한 다음, 수신기에서 사용하는 시크릿 관리 도구나 보호된 환경 설정에 저장하세요.

전체 값은 생성 또는 교체 직후에만 표시됩니다. 페이지를 새로고침하거나 나가면 Maildroppa는 시크릿의 존재 여부와 마지막 업데이트 시각만 표시하며, 저장된 시크릿 값은 다시 보여주지 않습니다.

웹훅: 새로 생성한 Signing secret

시크릿을 분실한 경우

수신기에 현재 시크릿이 없다면 “Rotate secret”을 클릭하고 새로 표시되는 값을 저장하세요.

교체 시 이전 시크릿은 즉시 새 값으로 대체됩니다. Maildroppa는 전환 기간을 두고 두 값을 함께 유지하지 않습니다. 추가 테스트를 보내거나 프로덕션 전송에 사용하기 전에 이 계정 시크릿을 사용하는 모든 수신기를 업데이트하세요.

새 전송, 예약된 재시도, 테스트, 재전송에는 HTTP 요청 시점의 현재 시크릿으로 서명합니다. 따라서 교체 전에 생성된 전송 건도 교체 후에 전송을 시도하면 새 시크릿으로 서명될 수 있습니다.

시크릿은 비밀번호처럼 관리하세요

Signing secret을 브라우저 코드, 공개 저장소, URL, 오류 페이지 또는 일반 애플리케이션 로그에 넣지 마세요.

시크릿은 서버 측 수신기에만 필요합니다. 노출이 의심되면 즉시 교체하고 모든 수신기를 업데이트하세요.

웹훅 서명 검증

각 요청에는 다음 Maildroppa 헤더가 포함됩니다.

X-Maildroppa-Event-Id — 비즈니스 이벤트를 식별합니다.
X-Maildroppa-Delivery-Id — 개별 전송 건을 식별합니다.
X-Maildroppa-Timestamp — 초 단위 Unix 타임스탬프로 나타낸 서명 시각입니다.
X-Maildroppa-Signature — 버전 정보가 포함된 HMAC 서명입니다.

Maildroppa는 다음 헤더도 전송합니다.

Content-Type: application/json
User-Agent: Maildroppa-Webhooks/1.0

서명 형식은 다음과 같습니다.

v1=<lowercase hexadecimal HMAC>

Maildroppa는 HMAC-SHA256으로 서명을 생성합니다. 서명 대상은 타임스탬프, 마침표, 변경되지 않은 원시 JSON 요청 본문을 순서대로 연결한 내용입니다.

<timestamp>.<raw request body>

HMAC 키로는 Signing secret을 사용하세요.

다음 Node.js 예제는 핵심 검증 과정을 보여줍니다. rawBody는 파싱 후 다시 직렬화한 JSON이 아니라 원래 요청의 바이트여야 합니다.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

서명을 검증한 뒤에는 타임스탬프를 서버 시간과도 비교하세요. 인프라에 맞게 5분과 같은 짧은 허용 시간 범위를 정하고, 이를 벗어난 요청은 거부하세요. 이렇게 하면 가로챈 유효한 요청이 훨씬 나중에 재전송되는 위험을 줄일 수 있습니다.

두 검증을 모두 통과한 후에만 JSON을 파싱하고 처리하세요.

서명 검증 오류의 일반적인 원인

서명 검증은 주로 다음 이유로 실패합니다.

시크릿 교체 후에도 수신기가 이전 시크릿을 사용합니다.
서명을 계산하기 전에 미들웨어가 JSON을 파싱하거나 변경했습니다.
수신기가 본문에만 서명하고 <timestamp>.를 누락했습니다.
타임스탬프를 헤더의 원래 값이 아닌 별도 형식의 날짜로 처리했습니다.
비교할 때 v1= 접두사를 누락했습니다.
계산한 HMAC을 소문자 16진수가 아닌 다른 형식으로 인코딩했습니다.

검증에 실패하면 Event ID와 Delivery ID를 로그에 기록하되, Signing secret이나 민감한 사용자 지정 헤더 값은 절대 기록하지 마세요.

2단계: 엔드포인트 추가

Endpoints 섹션에서 “Add endpoint”를 클릭하세요.

편집기는 다음 네 부분으로 구성됩니다.

Endpoint URL: 엔드포인트 URL
Events: 이벤트
Custom headers: 사용자 지정 헤더
Active status: 활성 상태

새 엔드포인트는 Active 상태로 시작하며, 편집기에 표시되는 모든 이벤트가 기본으로 선택되어 있습니다. 저장하기 전에 선택 항목을 검토해 수신기에 실제로 필요한 알림만 전송되도록 하세요.

웹훅: 엔드포인트 추가 대화 상자

엔드포인트 URL 설정

Maildroppa 요청을 받을 공개 URL을 전체 주소로 입력하세요. 예를 들면 다음과 같습니다.

https://integrations.example.com/webhooks/maildroppa

URL은 다음 요건을 충족해야 합니다.

https://를 사용해야 합니다.
유효한 공개 호스트 이름을 포함해야 합니다.
길이는 최대 2,048자입니다.
{ 또는 }가 들어간 템플릿 변수를 포함할 수 없습니다.
호스트 이름 앞에 사용자 이름이나 비밀번호를 포함할 수 없습니다.
#로 시작하는 URL 프래그먼트를 포함할 수 없습니다.
표준 HTTPS 포트인 443을 사용해야 합니다.
localhost나 IP 주소 자체를 사용할 수 없으며, 차단된 사설 네트워크 또는 예약된 네트워크 주소로 해석되는 호스트 이름도 사용할 수 없습니다.

쿼리 매개변수는 지원하지만, API 키나 기타 시크릿을 URL에 넣지 마세요. URL은 엔드포인트 목록과 전송 데이터에 표시됩니다. 인증 정보는 사용자 지정 헤더에 넣으세요.

Maildroppa는 리디렉션을 따르지 않습니다. 301, 302, 307 또는 308을 반환하는 URL 대신 최종 HTTPS 대상 URL을 저장하세요.

전송 전에 대상 호스트 이름의 주소를 다시 확인합니다. 엔드포인트를 저장할 때 유효했더라도 나중에 사설 주소나 차단된 주소로 해석되는 호스트 이름은 거부됩니다.

이벤트 선택

이벤트를 하나 이상 선택하세요. 엔드포인트는 편집기에서 선택한 이벤트 유형만 받습니다.

이 페이지에서 선택할 수 있는 이벤트는 다음과 같습니다.

Subscriber Created — `subscriber.created`

Maildroppa 계정에 구독자가 생성되면 전송됩니다.

이 이벤트를 사용해 CRM, 고객 데이터 플랫폼, 내부 데이터베이스 또는 수신 동의 여부를 반영하는 다른 시스템에 해당 연락처를 생성하세요.

이 이벤트가 발생했다고 해서 모든 구독 신청이 이중 수신 동의를 완료한 것은 아닙니다. 페이로드의 구독자 상태는 해당 구독자의 현재 상태를 나타냅니다.

Subscriber Updated — `subscriber.updated`

기본 구독자 정보 또는 사용자 지정 필드 값이 변경되면 전송됩니다.

페이로드에 포함된 전체 구독자 객체를 Maildroppa의 현재 구독자 데이터로 사용하세요. 특정 속성 하나만 변경되었다고 가정하지 마세요.

태그 할당과 제거는 별도의 이벤트 유형으로 제공되므로 각각 따로 처리할 수 있습니다.

Subscriber Unsubscribed — `subscriber.unsubscribed`

구독 해지 작업으로 구독자가 구독 해지 상태로 전환되면 전송됩니다.

이 이벤트를 사용해 연결된 시스템에서 해당 연락처를 발송 대상에서 제외하세요. 다른 시스템에 여전히 활성 연락처로 표시되어 있다는 이유로 자동으로 재구독 처리하지 마세요.

Tag Added — `subscriber.tag_added`

구독자에게 태그가 할당되면 전송됩니다.

페이로드에는 해당 변경과 관련된 구독자와 태그가 포함됩니다.

Tag Removed — `subscriber.tag_removed`

구독자에게서 태그가 제거되면 전송됩니다.

페이로드에는 업데이트된 구독자와 제거된 태그가 포함됩니다. 제거된 태그는 구독자의 현재 tags 배열에 더 이상 포함되지 않더라도 별도로 제공됩니다.

Form Submitted — `form.submitted`

방문자가 Maildroppa 구독 신청 양식을 제출하면 전송됩니다.

이 이벤트는 양식 제출을 알리는 신호이지, 이메일 확인을 거치는 이중 수신 동의가 완료되었다는 뜻은 아닙니다. 확인이 완료된 구독을 전제로 하는 워크플로에서는 구독자의 현재 상태와 확인 절차를 계속 반영해야 합니다.

담당 기능이 다르면 엔드포인트를 분리하세요

이벤트에 따라 서로 다른 시스템으로 전송할 수 있습니다. 예를 들면 다음과 같습니다.

구독자 및 태그 이벤트는 CRM으로 전송합니다.
구독 해지 이벤트는 발송 제외 관리 서비스로 전송합니다.
양식 제출 이벤트는 분석 파이프라인으로 전송합니다.

엔드포인트를 분리하면 불필요한 트래픽을 줄이고 오류를 더 쉽게 진단할 수 있습니다. 각 엔드포인트의 이벤트 선택, URL, 사용자 지정 헤더, 활성 상태, 테스트, 전송 기록은 개별적으로 관리됩니다.

사용자 지정 헤더 추가

사용자 지정 헤더는 선택 사항입니다. 수신기에 API 키, Bearer 토큰, 테넌트 식별자 또는 기타 고정 헤더가 필요할 때 사용하세요.

“Add header”를 클릭한 다음 Header name에 헤더 이름을, Header value에 값을 입력하세요. 다음과 같은 헤더를 사용할 수 있습니다.

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

사용자 지정 헤더는 최대 20개까지 추가할 수 있습니다.

헤더 이름의 요건은 다음과 같습니다.

필수 입력 항목입니다.
최대 128자까지 사용할 수 있습니다.
HTTP 헤더 이름에 허용되는 문자를 사용해야 합니다.
대소문자를 구분하지 않고 비교했을 때 중복되지 않아야 합니다.

헤더 값의 요건은 다음과 같습니다.

필수 입력 항목입니다.
최대 2,000자까지 사용할 수 있습니다.
줄바꿈을 포함할 수 없습니다.

다음 이름은 예약되어 있어 사용자 지정 헤더로 대체할 수 없습니다.

Content-Type
Content-Length
Host
User-Agent
X-Maildroppa-로 시작하는 모든 이름

이 제한은 사용자 지정 값이 Maildroppa의 전송 및 서명 헤더를 덮어쓰지 못하도록 합니다.

헤더 시크릿 저장 방식

Maildroppa는 사용자 지정 헤더 값을 암호화한 후 저장합니다. 저장된 값은 읽을 수 있는 형태로 브라우저에 반환되지 않습니다.

나중에 엔드포인트를 편집하면 값 입력란에 “Stored value kept”가 표시됩니다. 기존 시크릿을 그대로 유지하려면 입력란을 비워 두세요. 새 값을 입력하면 기존 값이 대체됩니다.

헤더 이름을 변경할 때는 값도 다시 입력하세요. Maildroppa는 원래 헤더 이름이 유지되는 경우에만 저장된 시크릿을 보존합니다.

헤더 행을 삭제하고 엔드포인트를 저장하면 이후 전송부터 해당 헤더가 제외됩니다.

사용자 지정 헤더 값은 저장된 요청 정보에서 민감 정보로 취급됩니다. 전송 기록에서는 실제 값 대신 마스킹된 값이 표시됩니다.

엔드포인트 활성화 및 비활성화 설정

엔드포인트가 즉시 이벤트를 받을 준비가 되었다면 “Active”를 선택한 상태로 두세요.

전송을 시작하지 않고 설정만 저장하려면 선택을 해제하세요. 나중에 엔드포인트 목록에서 활성화할 수 있습니다.

비활성 엔드포인트에는 다음 사항이 적용됩니다.

새로 발생한 이벤트를 받지 않습니다.
테스트 웹훅을 보낼 수 없습니다.
목록에 계속 표시되며 편집할 수 있습니다.
기존 전송 기록을 계속 확인할 수 있습니다.

엔드포인트를 활성화해도 비활성 상태일 때 발생한 이벤트가 소급해서 전송되지는 않습니다.

URL, 선택한 이벤트, 헤더, 상태가 올바른지 확인한 뒤 “Save”를 클릭하세요.

엔드포인트 목록 이해하기

각 엔드포인트 행에는 다음 정보가 표시됩니다.

대상 URL
Active 또는 Inactive 배지
구독한 이벤트 유형
사용자 지정 헤더 수
엔드포인트의 마지막 업데이트 시각

사용할 수 있는 작업은 다음과 같습니다.

On/Off — 엔드포인트를 활성화하거나 비활성화합니다.
Test — 활성 엔드포인트로 테스트 요청을 즉시 한 번 보냅니다.
Edit — URL, 이벤트, 헤더 또는 활성 상태를 변경합니다.
Delete — 확인 후 엔드포인트 설정을 영구적으로 삭제합니다.

행의 본문 영역을 선택하면 목록 아래에 해당 엔드포인트의 전송 기록이 열립니다.

웹훅: 활성 엔드포인트 행

설정 변경이 기존 전송에 미치는 영향

계정 이벤트가 발생하면 해당 시점의 엔드포인트 URL, 페이로드, 사용자 지정 헤더 스냅샷을 담은 전송 건이 생성됩니다.

URL이나 사용자 지정 헤더를 수정하면 새로 생성되는 전송 건에 적용됩니다. 이미 대기열에 있는 전송 건은 원래 대상과 저장된 헤더 설정을 유지합니다.

이벤트 선택을 변경해도 이후에 발생하는 이벤트에만 적용됩니다. 이벤트 발생 당시 선택되지 않았던 이벤트 유형에 대해 Maildroppa가 전송 건을 소급해서 생성하지는 않습니다.

Signing secret은 다릅니다. HTTP 요청을 준비하는 시점에 값을 읽습니다. 따라서 대기 중인 전송이나 재전송은 페이로드와 엔드포인트 스냅샷이 이전에 생성되었더라도 새로 교체된 Signing secret을 사용할 수 있습니다.

엔드포인트 테스트

수신기와 Signing secret이 준비되면 활성 엔드포인트에서 “Test”를 클릭하세요.

Maildroppa는 저장된 엔드포인트 URL과 사용자 지정 헤더를 사용해 서명된 요청을 즉시 한 번 전송합니다. 열려 있는 편집기의 저장되지 않은 변경 사항은 테스트에 반영되지 않습니다.

테스트 페이로드는 webhook.test 이벤트 유형을 사용하며, livemode 값을 false로 설정합니다.

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

실제 테스트에서 생성되는 ID와 타임스탬프는 매번 다릅니다.

테스트는 HTTP 전송을 정확히 한 번만 시도합니다. 테스트 전송에는 프로덕션 재시도 일정이 적용되지 않으며, 재전송도 할 수 없습니다.

요청이 완료되면 결과 패널에 다음 정보가 표시됩니다.

Test success 또는 Test failed
Event ID
응답을 받은 경우 HTTP 상태
소요 시간
Delivery ID
오류 정보가 있는 경우 해당 정보
수신기가 본문을 반환한 경우 응답 내용 일부

테스트는 전송 기록에도 Test 배지와 함께 표시됩니다. 테스트 요청만 보려면 “Test” 필터를 사용하세요.

웹훅: 테스트 전송 성공

프로덕션 페이로드 이해하기

프로덕션 계정 이벤트는 공통 JSON 외부 구조를 사용합니다.

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

최상위 속성의 의미는 다음과 같습니다.

id — Event ID입니다. X-Maildroppa-Event-Id와 일치합니다.
type — 엔드포인트 편집기에서 선택한 이벤트 키입니다.
schema_version — 페이로드 스키마 버전입니다. 이벤트 파싱 방식을 결정할 때 사용하세요.
created_at — 이벤트 페이로드가 생성된 시각이며, UTC 기준입니다.
livemode — 프로덕션 이벤트에서는 true, 테스트 이벤트에서는 false입니다.
data — 이벤트별 데이터입니다.

정확한 type 값을 기준으로 이벤트를 라우팅하세요. 연동에 필요하지 않은 추가 속성은 무시하도록 구현해, 호환성을 유지하는 페이로드 확장으로 수신기 작동에 문제가 생기지 않도록 하세요.

구독자 이벤트 페이로드

구독자 이벤트는 data.subscriber 안에 현재 구독자 데이터를 포함합니다.

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields와 tags는 배열이며, 비어 있을 수도 있습니다. 값이 없는 구독자 속성은 null일 수도 있습니다. 따라서 수신기는 모든 선택적 프로필 값이 존재한다고 가정하지 말고 페이로드 스키마에 따라 처리해야 합니다.

태그 이벤트 페이로드

태그 이벤트에는 구독자와 이벤트 발생 원인이 된 태그가 모두 포함됩니다.

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

subscriber.tag_removed의 경우, 구독자의 현재 tags 배열에 해당 태그가 더 이상 없더라도 data.tag를 통해 제거된 태그를 식별할 수 있습니다.

Event ID, Delivery ID와 멱등성

Event ID와 Delivery ID는 용도가 서로 다릅니다.

Event ID

Event ID는 비즈니스 이벤트를 식별하며, 다음 위치에서 확인할 수 있습니다.

페이로드의 최상위 id 속성
X-Maildroppa-Event-Id 요청 헤더
전송 기록

같은 이벤트가 이를 구독하는 여러 엔드포인트로 전송될 수 있습니다. 이 전송 건들은 같은 Event ID를 공유합니다.

재시도와 수동 재전송도 원래 Event ID를 유지합니다. 처리한 Event ID를 저장하고 비즈니스 작업의 멱등성을 보장하세요. 그러면 반복 요청으로 연락처가 중복 생성되거나, 되돌릴 수 없는 작업이 반복되거나, 같은 변경 사항이 두 번 적용되는 것을 방지할 수 있습니다.

Delivery ID

Delivery ID는 개별 전송 레코드를 식별하며, 다음 위치에서 확인할 수 있습니다.

X-Maildroppa-Delivery-Id 요청 헤더
전송 기록

각 엔드포인트의 전송 건에는 고유한 Delivery ID가 있습니다. 수동 재전송 시에는 원래 Event ID를 유지하면서 새 Delivery ID를 생성합니다.

기술적인 추적과 지원 요청에는 Delivery ID를 사용하세요. 비즈니스 작업 수준의 중복 제거에는 Event ID를 사용하세요.

올바른 HTTP 응답 반환

Maildroppa는 응답을 다음과 같이 분류합니다.

모든 2xx 응답은 전송 성공으로 처리됩니다.
408 Request Timeout, 429 Too Many Requests, 5xx 응답은 일시적인 실패로 간주되며 재시도할 수 있습니다.
일시적일 수 있는 네트워크 오류는 재시도합니다.
리디렉션 및 기타 3xx 응답은 따르지 않으며, 더 이상 시도하지 않는 최종 실패로 처리됩니다.
그 밖의 4xx 응답도 최종 실패로 처리되며 재시도하지 않습니다.

이벤트를 안전하게 수락한 경우에만 200, 202 또는 204를 반환하세요. 처리에 시간이 걸린다면 먼저 이벤트를 저장하고 성공 응답을 반환한 뒤, 시간이 오래 걸리는 작업은 비동기적으로 수행하세요.

다른 웹훅 URL로 연결되는 리디렉션을 반환하지 마세요. 대신 Maildroppa에 최종 URL을 설정하세요.

자동 재시도 일정

프로덕션 전송은 HTTP 전송을 최대 7번까지 시도할 수 있습니다.

재시도 가능한 오류가 발생하면 Maildroppa는 다음 대기 시간을 적용해 다음 시도를 예약합니다.

1차 시도 후: 1분
2차 시도 후: 5분
3차 시도 후: 30분
4차 시도 후: 2시간
5차 시도 후: 12시간
6차 시도 후: 24시간

7차 시도에서도 재시도 가능한 오류가 발생하면 해당 전송은 Dead 상태가 되며, 추가 자동 시도는 예약되지 않습니다.

대기 시간은 각 시도가 실패한 시점부터 계산합니다. 전송은 비동기적으로 처리되고 시스템 보호를 위한 제한도 적용되므로, 실제 전송 시각은 조금 늦어질 수 있습니다.

가능하면 “Next retry”에 표시된 시각 전에 수신기의 일시적인 문제를 해결하세요. 자동 시도가 모두 끝났다면 수신기가 정상화된 후 “Replay”를 사용하세요.

Delivery history 이해하기

Delivery history에는 현재 선택한 엔드포인트의 전송 기록이 표시됩니다. 섹션 제목 영역에 엔드포인트 URL이 함께 표시되므로 어떤 엔드포인트의 기록인지 확인할 수 있습니다.

다음 필터를 사용하세요.

All — 프로덕션 전송과 테스트 전송을 모두 표시합니다.
Production — 실제 운영 이벤트의 전송만 표시합니다.
Test — 수동 테스트만 표시합니다.

최신 상태를 불러오려면 “Refresh”를 클릭하세요. Maildroppa가 전송하거나 재시도하는 동안 전송 기록 화면을 열어 둘 필요는 없습니다.

페이지에는 선택한 필터 조건에 맞는 최신 전송 50건이 표시됩니다.

웹훅: 전송 기록 필터

전송 기록의 열 구성

각 행에는 다음 정보가 포함됩니다.

Created — 전송 레코드가 생성된 시각입니다.
State — Pending, Success, Failed 또는 Dead 상태입니다.
HTTP — 응답 상태, 시도 횟수, 소요 시간 및 해당하는 경우 다음 재시도 시각입니다.
Subscriber — 구독자와 관련된 이벤트인 경우 해당 구독자의 이메일 주소입니다.
Delivery — 이벤트 유형, Event ID, Delivery ID입니다.
Actions — 재전송이 가능한 경우 Replay가 표시됩니다.

HTTP 요청을 시도하지 않았다면 HTTP 열에 “No HTTP attempt”가 표시됩니다. 예를 들어 Signing secret이 없거나 저장된 대상을 더 이상 안전하게 사용할 수 없어 Maildroppa가 전송 전에 요청을 거부한 경우입니다.

정보가 있는 경우 행에 오류 정보인 Error와 수신기가 반환한 응답의 일부인 Response excerpt도 표시됩니다. 웹훅 응답 본문에 시크릿이나 민감한 개인정보를 넣지 마세요. 응답의 일부가 계정의 전송 로그에 표시될 수 있습니다.

전송 상태

Pending은 첫 전송 시도나 예약된 재시도를 기다리는 상태입니다. 다음 시도가 예약되어 있으면 “Next retry”가 표시됩니다.

Success는 수신기가 2xx 응답을 반환한 상태입니다. 추가 자동 시도는 필요하지 않습니다.

Failed는 재시도할 수 없는 문제로 전송이 종료되었거나, HTTP 시도 전에 요청이 거부되었거나, 전송 전에 중지된 상태입니다.

Dead는 재시도 가능한 문제로 자동 시도를 모두 소진했지만 성공 응답을 받지 못한 상태입니다.

기록 보존 기간

전송 레코드는 다음 기간 동안 보존됩니다.

성공한 프로덕션 전송: 30일
실패한 프로덕션 전송: 90일
Dead 상태의 프로덕션 전송: 90일
테스트 전송: 30일

감사 기록을 더 오래 보관해야 한다면 자체 연동 로그를 유지하세요. Event ID와 Delivery ID는 저장하되, 시크릿은 불필요하게 저장하지 마세요.

전송 건 재전송

처리가 끝난 프로덕션 전송 건을 다시 시도하려면 “Replay”를 클릭하세요.

Replay는 Success, Failed 또는 Dead 상태인 프로덕션 전송에 사용할 수 있습니다. Pending 상태에서는 사용할 수 없으며, 테스트 전송도 재전송할 수 없습니다.

재전송 시에는 다음과 같이 처리됩니다.

Pending 상태의 새 전송 건을 생성합니다.
새 Delivery ID를 생성합니다.
원래 Event ID를 유지합니다.
원래 이벤트 유형과 JSON 페이로드를 유지합니다.
원래 저장된 대상 URL과 사용자 지정 헤더 스냅샷을 사용합니다.
새 요청을 준비하는 시점의 Signing secret을 사용합니다.

재전송은 구독자의 현재 데이터로 페이로드를 다시 구성하지 않고, 원래 이벤트의 스냅샷을 다시 보냅니다. 따라서 재전송 내역을 감사할 수 있으며, 과거 이벤트의 의미가 의도치 않게 바뀌는 것을 방지할 수 있습니다.

동일한 원본 전송 건에 대해서는 한 번에 하나의 재전송만 Pending 상태로 대기할 수 있습니다. 다시 재전송을 요청하려면 진행 중인 재전송이 끝날 때까지 기다리세요.

재전송 전에 엔드포인트가 Active 상태인지 확인하세요. 비활성 상태라면 대기열에 있는 재전송이 성공적으로 전달될 수 없습니다.

Maildroppa가 성공 응답을 받지 못했더라도 수신기에서는 비즈니스 작업이 이미 완료되었을 수 있으므로, 재전송 시 중복 요청이 발생할 수 있습니다. Event ID로 중복을 제거하면 연결된 시스템에서 같은 작업이 반복되는 것을 방지할 수 있습니다.

엔드포인트 편집

URL, 이벤트 선택, 사용자 지정 헤더 또는 활성 상태를 변경하려면 “Edit”를 클릭하세요.

저장 전 확인 사항과 저장 후 테스트 절차는 다음과 같습니다.

새 URL을 이미 사용할 수 있는지 확인하세요.
저장된 헤더 값을 그대로 유지하려면 값 입력란을 비워 두세요.
이름을 변경한 모든 헤더에 새 값을 입력하세요.
필요한 알림이 실수로 제외되지 않도록 선택한 이벤트를 검토하세요.
저장한 뒤 새 테스트 웹훅을 보내세요.

대기열에 있는 전송 건은 기존 URL과 사용자 지정 헤더 스냅샷을 유지합니다. 새 설정이 이미 대기 중인 요청에도 반영된다고 가정하지 말고, 앞으로 생성될 전송을 기준으로 새 설정을 테스트하세요.

엔드포인트 비활성화

설정과 기록을 삭제하지 않고 연동을 일시 중지하려면 On/Off 스위치를 사용하세요.

엔드포인트를 Off로 전환하면 다음과 같이 처리됩니다.

새 이벤트가 해당 엔드포인트의 전송 대기열에 더 이상 추가되지 않습니다.
Pending 상태인 전송 중 아직 전송 작업에 할당되지 않은 건은 Failed로 표시됩니다.
Test가 비활성화됩니다.
엔드포인트는 그대로 유지되며, 편집하거나 나중에 다시 활성화할 수 있습니다.

비활성화 시점에 이미 진행 중인 요청은 그대로 완료될 수 있습니다. 연동 운영에서 이 차이가 중요하다면 엔드포인트를 Off로 전환한 뒤 전송 기록을 확인하세요.

엔드포인트가 비활성 상태일 때 놓친 이벤트는 다시 On으로 전환해도 소급해서 전송되지 않습니다.

엔드포인트 삭제

엔드포인트가 더 이상 필요하지 않다면 “Delete”를 클릭하고 경고를 확인한 뒤 삭제를 확정하세요.

삭제하면 엔드포인트가 페이지에서 사라지고 이후 이벤트 전송이 중단됩니다. Pending 상태인 전송 중 아직 전송 작업에 할당되지 않은 건은 실패 처리됩니다.

Delete는 일시 중지 기능이 아닙니다. 나중에 설정이나 화면에 표시되는 기록이 다시 필요할 수 있다면 On/Off 스위치를 사용하세요.

삭제하기 전에 연동 감사에 필요한 Event ID와 Delivery ID를 기록해 두세요.

문제 해결

엔드포인트를 저장할 수 없는 경우

다음 사항을 확인하세요.

URL이 https://로 시작하는지 확인하세요.
URL이 공개 호스트 이름과 포트 443을 사용하는지 확인하세요.
URL에 변수, 로그인 정보 또는 프래그먼트가 없는지 확인하세요.
이벤트를 하나 이상 선택했는지 확인하세요.
모든 사용자 지정 헤더에 중복되지 않는 이름과 값이 입력되어 있는지 확인하세요.
예약된 Maildroppa 및 HTTP 헤더 이름을 사용자 지정 헤더 이름으로 사용하지 않았는지 확인하세요.

Test가 비활성화된 경우

Test는 Active 상태의 엔드포인트에서만 사용할 수 있습니다. 엔드포인트를 On으로 전환하거나 편집 화면에서 “Active”를 선택한 다음, 저장하고 테스트하세요.

테스트에 HTTP 시도가 표시되지 않는 경우

상태가 Missing이면 Signing secret을 생성하세요. 대상 호스트 이름이 공개 호스트 이름이며 여전히 올바른 주소로 해석되는지도 확인하세요.

시크릿, URL 또는 사용자 지정 헤더가 유효하지 않거나 대상 안전성 검사에 실패하면 전송 전에 요청이 거부될 수 있습니다.

수신기가 `401` 또는 `403`을 반환하는 경우

저장된 사용자 지정 헤더 이름과 인증 정보를 확인하세요. 정보가 변경되었다면 엔드포인트를 편집하고 값을 다시 입력하세요.

수신기가 자체 API 인증 정보와 Maildroppa 서명을 혼동하고 있지 않은지도 확인하세요. 사용자 지정 authorization 헤더와 X-Maildroppa-Signature는 용도가 다르며, 각각 독립적으로 검증할 수 있습니다.

수신기가 리디렉션을 반환하는 경우

Maildroppa는 리디렉션을 따르지 않습니다. 엔드포인트 URL을 최종 공개 HTTPS URL로 바꾸고 다시 테스트하세요.

서명이 일치하지 않는 경우

수신기가 다음과 같이 처리하는지 확인하세요.

현재 Signing secret을 사용합니다.
X-Maildroppa-Timestamp 값을 정확히 그대로 사용합니다.
<timestamp>.<raw request body>에 서명합니다.
HMAC-SHA256을 사용하고 결과를 소문자 16진수로 출력합니다.
v1=을 포함한 전체 값을 비교합니다.
JSON 파싱으로 본문이 변경되기 전에 비교합니다.

같은 이벤트가 여러 번 도착하는 경우

네트워크 중단, 재시도 또는 수동 재전송 후에 발생할 수 있습니다. 웹훅 전송 시스템이 '정확히 한 번'이 아닌 '최소 한 번' 전송 방식을 제공하는 것은 일반적입니다.

Event ID를 멱등성 키로 사용하세요. 이미 처리한 Event ID가 다시 수신되었고 추가 작업이 필요하지 않다면 2xx 응답을 반환하세요.

전송이 Pending 상태인 경우

HTTP 열의 “Next retry”를 확인하세요. 재시도 가능한 408, 429, 5xx 응답이나 일시적인 네트워크 오류가 발생하면 다음 예약된 시도까지 Pending 상태가 유지됩니다.

재시도 시각이 지난 뒤 “Refresh”를 클릭해 최신 상태를 불러오세요.

전송이 Dead 상태인 경우

자동 시도를 모두 소진한 상태입니다. 먼저 수신기의 문제를 해결하고 엔드포인트가 Active 상태인지 확인하세요. 그런 다음 테스트 웹훅을 보내고, 해당 프로덕션 전송 건에서 “Replay”를 사용하세요.

프로덕션 운영 권장 체크리스트

엔드포인트를 프로덕션 운영에 사용하기 전에 다음 사항을 모두 확인하세요.

수신기가 유효한 인증서가 적용된 안정적인 공개 HTTPS URL을 사용합니다.
Signing secret이 소스 코드 외부에 저장되어 있습니다.
변경되지 않은 원시 본문을 기준으로 서명을 검증합니다.
문서화된 허용 시간 범위에 따라 오래된 타임스탬프를 거부합니다.
수신기가 Event ID를 저장하고 중복을 제거합니다.
수신기가 추적을 위해 Event ID와 Delivery ID를 로그에 기록합니다.
시간이 오래 걸리는 처리는 이벤트를 영속적으로 저장해 수락한 후에 수행합니다.
수락한 이벤트에 대해서만 2xx 응답을 반환합니다.
사용자 지정 인증 정보를 URL이 아닌 헤더에 저장합니다.
필요한 이벤트 유형만 선택되어 있습니다.
테스트 웹훅 전송이 성공하고 전송 기록에도 올바르게 표시됩니다.
프로덕션 전송에서 오류가 발생하기 시작하면 모니터링을 통해 알림을 받을 수 있습니다.

이러한 보호 조치를 갖추면 Webhooks 페이지를 통해 안정적인 연동에 필요한 두 가지를 모두 확보할 수 있습니다. 애플리케이션에 이벤트를 안전하게 전달하고, Maildroppa 안에서 운영 기록을 명확하게 확인할 수 있습니다.

목차

이메일 도구로 이메일 마케팅을 간편하게