웹훅 구성

Published: 2026년 7월 16일 · Last updated: 2026년 7월 21일 · By Marcus Biel

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

Maildroppa에 구독자가 생성되었는지, 업데이트되었는지, 구독 취소되었는지 또는 태그가 할당되었는지를 반복해서 묻는 대신, 이벤트가 발생한 직후 애플리케이션이 HTTPS 요청을 받을 수 있습니다.

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

계정 웹훅 작동 방식

계정 웹훅은 다음 과정으로 작동합니다.

1. Maildroppa에서 이벤트가 발생합니다. 예를 들어 구독자가 생성됩니다.
2. Maildroppa가 해당 이벤트를 구독한 모든 활성 엔드포인트를 찾습니다.
3. Maildroppa가 일치하는 각 엔드포인트에 대해 하나의 전송을 생성합니다.
4. JSON 페이로드가 계정의 웹훅 Signing secret으로 서명됩니다.
5. Maildroppa가 저장된 엔드포인트 URL로 HTTPS POST 요청을 보냅니다.
6. 엔드포인트가 서명을 확인하고 이벤트를 저장하거나 처리한 다음 HTTP 응답을 반환합니다.
7. Maildroppa가 결과를 Delivery history에 기록하고 일시적인 오류를 자동으로 재시도합니다.

여러 엔드포인트가 같은 이벤트를 구독하면 각 엔드포인트가 자체 전송을 받습니다. 모든 전송에서 비즈니스 이벤트의 Event ID는 같지만, 각 전송에는 고유한 Delivery ID가 있습니다.

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

Webhooks 페이지 열기

“Settings”를 열고 “Developers”를 확장한 다음 “Webhooks”를 선택합니다.

페이지에는 세 가지 주요 영역이 있습니다.

• Signing secret
• Endpoints
• 선택한 엔드포인트의 Delivery history

엔드포인트가 두 개 이상이면 엔드포인트 행을 선택하여 해당 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는 시크릿이 존재한다는 사실과 마지막 업데이트 시각만 표시합니다. 저장된 시크릿을 다시 공개하지 않습니다.

시크릿을 잃어버린 경우

수신기에 현재 시크릿이 더 이상 없다면 “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
• 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은 엔드포인트 목록과 전송 데이터에 표시됩니다. 자격 증명에는 Custom header를 사용하세요.

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

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

이벤트 선택

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

페이지에서 제공하는 이벤트 선택 항목은 다음과 같습니다.

Subscriber Created — subscriber.created

Maildroppa 계정에서 구독자가 생성될 때 전송됩니다.

이 이벤트를 사용하여 CRM, 고객 데이터 플랫폼, 내부 데이터베이스 또는 권한을 인식하는 다른 시스템에 해당 연락처를 생성하세요.

이 이벤트를 모든 가입이 Double Opt-in을 완료했다는 증거로 해석하지 마세요. 페이로드의 구독자 상태는 현재 상태를 설명합니다.

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 가입 양식을 제출할 때 전송됩니다.

이를 양식 제출 신호로 처리하고 Double Opt-in이 완료되었다는 확인으로 사용하지 마세요. 확인된 구독이 필요한 모든 워크플로는 구독자의 현재 상태와 확인 절차를 계속 준수해야 합니다.

책임이 다르면 엔드포인트를 분리하세요

서로 다른 이벤트를 서로 다른 시스템으로 보낼 수 있습니다. 예를 들면 다음과 같습니다.

• 구독자 및 태그 이벤트를 CRM으로 전송합니다.
• 구독 취소 이벤트를 억제 서비스로 전송합니다.
• 양식 제출 이벤트를 분석 파이프라인으로 전송합니다.

엔드포인트를 분리하면 불필요한 트래픽이 줄고 오류를 진단하기 쉬워집니다. 각 엔드포인트에는 자체 이벤트 선택, URL, 사용자 지정 헤더, 활성 상태, 테스트 및 Delivery history가 있습니다.

사용자 지정 헤더 추가

사용자 지정 헤더는 선택 사항입니다. 수신기에 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는 원래 헤더 이름이 변경되지 않은 동안에만 저장된 시크릿을 유지합니다.

헤더 행을 제거하면 엔드포인트 저장 후 이후 전송에서 해당 헤더가 제거됩니다.

사용자 지정 헤더 값은 저장된 요청 정보에서 민감한 값으로 처리됩니다. Delivery history에는 마스킹되어 표시됩니다.

엔드포인트 활성 또는 비활성 설정

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

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

비활성 엔드포인트는 다음과 같습니다.

• 새로 발생한 이벤트를 받지 않습니다.
• Test webhook을 보낼 수 없습니다.
• 계속 표시되고 편집할 수 있습니다.
• 기존 Delivery history를 계속 확인할 수 있습니다.

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

URL, 이벤트 선택, 헤더 및 상태가 올바르면 “Save”를 클릭합니다.

엔드포인트 목록 이해하기

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

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

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

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

행의 주요 부분을 선택하면 목록 아래에 해당 엔드포인트의 Delivery history가 열립니다.

저장된 변경 사항이 기존 전송에 미치는 영향

계정 이벤트가 발생하면 그 시점의 엔드포인트 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 배지와 함께 Delivery history에도 표시됩니다. “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 요청 헤더
• Delivery history

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

재시도 및 수동 재생도 원래 Event ID를 유지합니다. 처리한 Event ID를 저장하고 비즈니스 작업을 멱등적으로 만들어 반복 요청이 중복 연락처를 생성하거나 되돌릴 수 없는 작업을 반복하거나 같은 변경 사항을 두 번 적용하지 않도록 하세요.

Delivery ID

Delivery ID는 하나의 전송 레코드를 식별합니다. 다음 위치에 표시됩니다.

• X-Maildroppa-Delivery-Id 요청 헤더
• Delivery history

각 엔드포인트 전송에는 고유한 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을 구성하세요.

자동 재시도 일정

프로덕션 전송은 최대 7번의 HTTP 시도를 수행할 수 있습니다.

재시도 가능한 오류가 발생하면 Maildroppa는 다음 지연 시간에 따라 다음 시도를 예약합니다.

1. 시도 1 후: 1분
2. 시도 2 후: 5분
3. 시도 3 후: 30분
4. 시도 4 후: 2시간
5. 시도 5 후: 12시간
6. 시도 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”를 클릭합니다.

저장하기 전에 다음을 확인하세요.

1. 새 URL을 이미 사용할 수 있는지 확인합니다.
2. 저장된 헤더 값을 변경하지 않을 경우 비워 둡니다.
3. 이름을 바꾼 모든 헤더에 새 값을 입력합니다.
4. 필요한 알림이 실수로 제거되지 않도록 이벤트 선택을 검토합니다.
5. 저장하고 새 Test webhook을 보냅니다.

대기 중인 전송은 기존 URL과 사용자 지정 헤더 스냅샷을 유지한다는 점을 기억하세요. 새 구성이 이전에 대기 중인 요청을 변경한다고 가정하지 말고 향후 전송을 위해 새 구성을 테스트하세요.

엔드포인트 비활성화

구성과 기록을 삭제하지 않고 통합을 일시 중지하려면 On/Off 스위치를 사용하세요.

엔드포인트를 Off로 전환하면 다음과 같습니다.

• 새 이벤트가 더 이상 해당 엔드포인트에 대기열로 추가되지 않습니다.
• 전송을 위해 이미 확보되지 않은 Pending 전송은 Failed로 표시됩니다.
• Test가 비활성화됩니다.
• 엔드포인트는 편집 및 이후 활성화를 위해 계속 사용할 수 있습니다.

비활성화 시점에 이미 진행 중인 요청은 계속 완료될 수 있습니다. 이 차이가 통합에 중요하다면 엔드포인트를 Off로 전환한 후 Delivery history를 확인하세요.

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

엔드포인트 삭제

엔드포인트를 더 이상 유지하지 않으려면 “Delete”를 클릭하고 경고를 확인합니다.

삭제하면 페이지에서 엔드포인트가 제거되고 향후 이벤트 전송이 중지되며, 전송을 위해 이미 확보되지 않은 Pending 전송은 실패 처리됩니다.

Delete는 일시적인 일시 중지 방법이 아닙니다. 나중에 구성이나 표시된 기록이 필요할 수 있다면 On/Off 스위치를 사용하세요.

삭제하기 전에 통합 감사에 필요한 Event ID 또는 Delivery ID를 기록하세요.

문제 해결

엔드포인트를 저장할 수 없음

다음을 확인하세요.

• URL이 https://로 시작합니다.
• URL이 공개 호스트 이름과 포트 443을 사용합니다.
• URL에 변수, 로그인 정보 또는 프래그먼트가 없습니다.
• 하나 이상의 이벤트가 선택되어 있습니다.
• 모든 Custom header에 고유한 이름과 값이 있습니다.
• 예약된 Maildroppa 및 HTTP 헤더를 사용자 지정 이름으로 사용하지 않았습니다.

Test가 비활성화됨

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

Test에 HTTP 시도가 표시되지 않음

상태가 Missing이면 Signing secret을 생성하세요. 또한 대상 호스트 이름이 공개되어 있고 여전히 올바르게 확인되는지 확인하세요.

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

수신기가 401 또는 403을 반환함

저장된 Custom header 이름과 자격 증명을 확인하세요. 변경되었다면 엔드포인트를 편집하고 값을 다시 입력하세요.

또한 수신기가 자체 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인지 확인한 다음 Test webhook을 보내고 프로덕션 전송에서 Replay를 사용하세요.

프로덕션 권장 체크리스트

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

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

이러한 보호 조치를 마련하면 Webhooks 페이지는 안정적인 통합에 필요한 양쪽 기능을 모두 제공합니다. 즉, 애플리케이션으로의 안전한 이벤트 전송과 Maildroppa 내부의 명확한 운영 기록입니다.