메인 콘텐츠로 건너뛰기
Webhook Cover Image
웹훅은 Dodo Payments 계정에서 특정 이벤트가 발생할 때 실시간 알림을 제공합니다. 웹훅을 사용하여 워크플로를 자동화하고, 데이터베이스를 업데이트하며, 알림을 전송하고, 시스템을 동기화 상태로 유지하세요.
당사의 웹훅 구현은 Standard Webhooks 사양을 따르며 업계 모범 사례 및 기존 웹훅 라이브러리와의 호환성을 보장합니다.

주요 기능

Real-time Delivery

이벤트 발생 시 즉시 알림 수신

Secure by Default

HMAC SHA256 서명 검증 포함

Automatic Retries

지수 백오프가 적용된 내장 재시도 로직

Event Filtering

필요한 이벤트만 구독

시작하기

1

Access Webhook Settings

DodoPayments 대시보드로 이동하여 Settings > Webhooks로 이동합니다.
2

Create Webhook Endpoint

새 웹훅 엔드포인트를 만들려면 Add Webhook를 클릭합니다.
Add Webhook
3

Add Endpoint URL

웹훅 이벤트를 수신할 URL을 입력하세요.
4

Select Events to Receive

이벤트 목록에서 선택하여 웹훅 엔드포인트가 수신할 특정 이벤트를 선택하세요.
선택한 이벤트만 엔드포인트에 웹훅을 트리거하여 불필요한 트래픽과 처리를 방지할 수 있습니다.
5

Get Secret Key

설정 페이지에서 웹훅 Secret Key를 가져오세요. 수신한 웹훅의 진위를 확인할 때 이 값을 사용합니다.
웹훅 비밀 키를 안전하게 보관하고 클라이언트 측 코드나 공개 저장소에 절대 노출하지 마세요.
6

Rotate Secret (Optional)

필요한 경우 보안을 강화하기 위해 웹훅 비밀을 교체할 수 있습니다. 웹훅 설정에서 비밀 교체(Rotate Secret) 버튼을 클릭하세요.
비밀을 교체하면 기존 비밀은 만료되고 새 비밀로 대체됩니다. 이전 비밀은 다음 24시간 동안만 유효합니다. 이후에는 이전 비밀로 검증을 시도하면 실패합니다.
현재 비밀이 유출되었다고 의심되면 주기적으로 또는 즉시 비밀을 교체하세요.

구독한 이벤트 구성하기

각 웹훅 엔드포인트에 대해 수신할 특정 이벤트를 구성할 수 있습니다.

이벤트 구성 접근하기

1

Navigate to Webhook Details

Dodo Payments 대시보드로 이동하여 Settings > Webhooks로 이동하세요.
2

Select Your Endpoint

구성하려는 웹훅 엔드포인트를 클릭하세요.
3

Open Event Settings

웹훅 세부 정보 페이지에서 “Subscribed events” 섹션을 확인하세요. 이벤트 구독을 수정하려면 편집(Edit) 버튼을 클릭합니다.

이벤트 구독 관리하기

1

View Available Events

인터페이스에는 모든 사용 가능한 웹훅 이벤트가 계층 구조로 구성되어 표시됩니다. 이벤트는 카테고리별로 그룹화됩니다(예: dispute, payment, subscription).
2

Search and Filter

검색 표시줄을 사용하여 이벤트 이름이나 키워드를 입력하면 특정 이벤트를 빠르게 찾을 수 있습니다.
3

Select Events

수신하려는 이벤트 옆의 체크박스를 확인하세요. 다음을 수행할 수 있습니다:
  • 개별 하위 이벤트 선택 (예: dispute.accepted, dispute.challenged)
  • 관련된 모든 하위 이벤트를 수신하기 위해 상위 이벤트 선택
  • 필요에 따라 특정 이벤트를 조합하여 선택
4

Review Event Details

각 이벤트 옆 정보 아이콘(ⓘ) 위에 커서를 올리면 해당 이벤트가 언제 트리거되는지 설명이 표시됩니다.
5

Save Configuration

**저장(Save)**을 클릭하여 변경 사항을 적용하거나 **취소(Cancel)**를 클릭하여 수정을 취소하세요.
모든 이벤트를 선택 취소하면 웹훅 엔드포인트는 알림을 받지 않습니다. 애플리케이션이 제대로 작동하기 위해 필요한 이벤트는 최소한 하나 이상 선택되어 있는지 확인하세요.

웹훅 전송

타임아웃

웹훅은 연결 및 읽기 작업 모두에 대해 15초 타임아웃 창을 가집니다. 타임아웃을 피하기 위해 엔드포인트가 빠르게 응답하도록 하세요.
웹훅을 비동기로 처리하려면 수신 즉시 200 상태 코드를 반환하여 수신을 확인한 다음 실제 처리는 백그라운드에서 수행하세요.

자동 재시도

웹훅 전송이 실패하면 Dodo Payments는 시스템이 과부하되지 않도록 지수 백오프를 사용하여 자동으로 재시도합니다.
시도지연설명
1즉시첫 번째 재시도는 즉시 발생
25초두 번째 시도는 짧은 지연 후
35분세 번째 시도는 증가된 백오프와 함께
430분네 번째 시도는 계속된 백오프
52시간다섯 번째 시도는 연장된 지연과 함께
65시간여섯 번째 시도는 더 긴 지연과 함께
710시간일곱 번째 시도는 최대 지연과 함께
810시간최종 시도 - 실패한 경우 웹훅이 실패로 표시됨
웹훅 이벤트당 최대 8회 재시도가 수행됩니다. 예를 들어 웹훅이 세 번 실패한 뒤 성공하면, 첫 시도부터 총 전송 시간은 약 35분 5초입니다.
Dodo Payments 대시보드를 사용하여 개별 메시지를 수동으로 재시도하거나 언제든지 모든 실패한 메시지를 일괄 복구할 수 있습니다.

멱등성

각 웹훅 이벤트에는 고유한 webhook-id 헤더가 포함됩니다. 이 식별자를 사용하여 멱등성을 구현하고 중복 처리를 방지하세요.
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
항상 멱등성 검사를 구현하세요. 재시도로 인해 동일한 이벤트를 여러 번 받을 수 있습니다.

이벤트 순서

웹훅 이벤트는 재시도 또는 네트워크 조건으로 인해 순서가 뒤바뀔 수 있습니다. 시스템이 어떤 순서로든 이벤트를 처리할 수 있도록 설계하세요.
웹훅 이벤트가 원래 발생된 시점과 관계없이 전송 시 최신 페이로드를 수신합니다.

웹훅 보안

웹훅의 보안을 보장하기 위해 항상 페이로드를 검증하고 HTTPS를 사용하세요.

서명 검증

각 웹훅 요청에는 webhook-signature 헤더가 포함되며, 이는 웹훅 페이로드와 타임스탬프의 HMAC SHA256 서명으로 비밀 키로 서명됩니다.

SDK 검증(권장)

모든 공식 SDK에는 수신된 웹훅을 안전하게 검증하고 구문 분석하는 내장 도우미가 포함되어 있습니다. 두 가지 방법이 제공됩니다:
  • unwrap(): 웹훅 비밀 키를 사용하여 서명을 검증합니다
  • unsafe_unwrap(): 검증 없이 페이로드를 파싱합니다
Dodo Payments 클라이언트를 초기화할 때 DODO_PAYMENTS_WEBHOOK_KEY을 통해 웹훅 비밀을 제공하세요.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

수동 검증(대안)

SDK를 사용하지 않는 경우, Standard Webhooks 사양에 따라 서명을 직접 검증할 수 있습니다:
  1. webhook-id, webhook-timestamp, 정확한 원시 문자열화된 payload를 마침표( .)로 구분하여 서명된 메시지를 구성합니다.
  2. 대시보드에서 가져온 웹훅 비밀 키를 사용하여 해당 문자열의 HMAC SHA256을 계산합니다.
  3. 계산된 서명과 webhook-signature 헤더를 비교합니다. 일치하면 웹훅이 인증된 것입니다.
우리는 Standard Webhooks 사양을 따릅니다. 서명을 검증하려면 해당 라이브러리를 사용할 수 있습니다: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. 이벤트 페이로드 형식은 Webhook Payload를 참조하세요.

웹훅에 응답하기

  • 이벤트를 수신했음을 확인하려면 웹훅 핸들러가 2xx status code를 반환해야 합니다.
  • 그 외의 응답은 실패로 간주되며 웹훅은 재시도됩니다.

모범 사례

웹훅 엔드포인트에는 항상 HTTPS URL을 사용하세요. HTTP 엔드포인트는 중간자 공격에 취약하며 웹훅 데이터를 노출할 수 있습니다.
웹훅을 수신하면 즉시 200 상태 코드를 반환하세요. 이벤트 처리는 비동기로 수행하여 시간 초과를 방지하세요.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
webhook-id 헤더를 사용하여 멱등성을 구현하면 동일한 이벤트를 여러 번 안전하게 처리할 수 있습니다.
웹훅 비밀은 환경 변수나 시크릿 관리자 등 안전한 장소에 보관하세요. 절대로 버전 관리에 비밀을 커밋하지 마세요.

웹훅 페이로드 구조

웹훅 페이로드 구조를 이해하면 이벤트를 올바르게 구문 분석하고 처리하는 데 도움이 됩니다.

요청 형식

POST /your-webhook-url
Content-Type: application/json

헤더

webhook-id
string
필수
이 웹훅 이벤트의 고유 식별자입니다. 멱등성 검사에 사용하세요.
webhook-signature
string
필수
웹훅 진위를 확인하기 위한 HMAC SHA256 서명입니다.
webhook-timestamp
string
필수
웹훅이 전송된 시점의 유닉스 타임스탬프(초 단위)입니다.

요청 본문

business_id
string
필수
당신의 Dodo Payments 비즈니스 식별자입니다.
type
string
필수
이 웹후크를 트리거한 이벤트 유형(예: payment.succeeded, subscription.active).
timestamp
string
필수
이벤트가 발생한 시점의 ISO 8601 형식 타임스탬프입니다.
data
object
필수
이벤트에 대한 자세한 정보를 포함하는 이벤트별 페이로드입니다.

예제 페이로드

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

웹훅 테스트

Dodo Payments 대시보드에서 웹훅 통합을 직접 테스트하여 엔드포인트가 올바르게 작동하는지 확인할 수 있습니다.
Endpoint Details

테스트 인터페이스 접근하기

1

Navigate to Webhooks

Dodo Payments 대시보드로 이동하여 Settings > Webhooks로 이동하세요.
2

Select Your Endpoint

웹훅 엔드포인트를 클릭하여 세부 정보 페이지에 접근하세요.
3

Open Testing Tab

테스트 탭을 클릭하여 웹훅 테스트 인터페이스에 접근하세요.

웹훅 테스트하기

테스트 인터페이스는 웹훅 엔드포인트를 테스트하는 포괄적인 방법을 제공합니다:
1

Select Event Type

드롭다운 메뉴를 사용하여 테스트할 특정 이벤트 유형을 선택하세요(예: payment.succeeded, payment.failed 등).
드롭다운에는 엔드포인트가 수신할 수 있는 모든 웹훅 이벤트 유형이 포함됩니다.
2

Review Schema and Example

인터페이스에는 선택한 이벤트 유형에 대한 스키마(데이터 구조)와 예시(샘플 페이로드)가 모두 표시됩니다.
3

Send Test Event

예시 전송(Send Example) 버튼을 클릭하여 테스트 웹훅을 엔드포인트로 전송하세요.
중요: 테스트 인터페이스를 통해 전송된 실패한 메시지는 재시도되지 않습니다. 이 기능은 테스트용입니다.

테스트 검증하기

1

Check Your Endpoint

테스트 이벤트가 수신되었는지 확인하려면 웹훅 엔드포인트 로그를 모니터링하세요.
2

Verify Signature

테스트 페이로드로 서명 검증이 올바르게 작동하는지 확인하세요.
3

Test Response

엔드포인트가 수신을 확인하기 위해 2xx 상태 코드를 반환하는지 확인하세요.

구현 예제

웹훅 검증 및 처리를 보여주는 완전한 Express.js 구현 예제입니다:
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
app.use(express.json());

const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

app.post('/webhook/dodo-payments', async (req, res) => {
  try {
    // Extract webhook headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify the webhook signature
    const payload = JSON.stringify(req.body);
    await webhook.verify(payload, webhookHeaders);
    
    // Acknowledge receipt immediately
    res.status(200).json({ received: true });
    
    // Process webhook asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature' });
  }
});

async function processWebhookAsync(data: any) {
  // Handle the webhook event based on type
  switch (data.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(data);
      break;
    case 'subscription.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
운영 환경 이벤트를 처리하기 전에 대시보드 테스트 인터페이스를 사용하여 웹훅 핸들러를 철저히 테스트하세요. 이는 문제를 조기에 발견하고 수정하는 데 도움이 됩니다.

CLI로 웹훅 테스트

Dodo Payments CLI는 터미널을 벗어나지 않고도 로컬 개발 중 웹훅을 테스트할 수 있는 두 가지 명령을 제공합니다.

로컬에서 실시간 웹훅 수신

테스트 모드 계정의 실제 웹훅 이벤트를 로컬 개발 서버로 실시간 전송하려면:
dodo wh listen
CLI는 Dodo Payments에 WebSocket 연결을 열어 모든 웹훅 이벤트를 로컬 엔드포인트(예: http://localhost:3000/webhook)로 전달하며, 서명 검증 테스트를 위한 서명 헤더를 포함한 모든 헤더를 그대로 유지합니다.
리스너는 테스트 모드 API 키에서만 작동합니다. 이 명령을 사용하기 전에 dodo login를 실행하여 테스트 모드를 선택하세요.

모의 웹훅 이벤트 트리거

실제 거래를 만들지 않고도 모의 웹훅 페이로드를 모든 엔드포인트로 전송하려면:
dodo wh trigger
이 인터랙티브 도구를 사용하면 지원되는 22개 이벤트 유형 모두를 선택할 수 있으며, 실제 같은 모의 페이로드를 엔드포인트로 전송합니다. 한 세션에서 여러 이벤트를 테스트할 수 있도록 반복 실행됩니다.
dodo wh trigger에서 생성된 모의 웹훅 페이로드는 서명되지 않습니다. 테스트 중에만 웹훅 핸들러에서 unwrap() 대신 unsafe_unwrap()를 사용하세요.

CLI Webhook Testing Docs

전체 CLI 웹훅 테스트 설명서를 참조하세요

고급 설정

고급 설정 탭은 웹훅 엔드포인트 동작을 세부 조정할 수 있는 추가 구성 옵션을 제공합니다.

속도 제한(스로틀링)

시스템 과부하를 방지하기 위해 웹훅 이벤트가 엔드포인트로 전달되는 속도를 제어하세요.
1

Access Rate Limit Settings

고급(Advanced) 탭에서 “속도 제한(스로틀링)” 섹션을 찾으세요.
2

Configure Rate Limit

편집(Edit) 버튼을 클릭하여 속도 제한 설정을 수정하세요.
기본적으로 웹훅에는 “제한 없음(No rate limit)“이 적용되어 이벤트가 발생하는 즉시 전달됩니다.
3

Set Limits

원하는 속도 제한을 구성하여 웹훅 전달 빈도를 제어하고 시스템 과부하를 방지하세요.
이벤트를 처리하는 시간이 필요하거나 여러 이벤트를 함께 배치 처리하려는 경우에는 속도 제한을 활용하세요.

커스텀 헤더

웹훅 요청에 커스텀 HTTP 헤더를 추가하세요. 이는 인증, 라우팅 또는 메타데이터 추가에 유용합니다.
1

Add Custom Header

“커스텀 헤더” 섹션에서 커스텀 헤더의 을 입력하세요.
2

Add Multiple Headers

+ 버튼을 클릭하여 필요한 만큼 커스텀 헤더를 추가하세요.
3

Save Configuration

커스텀 헤더는 이 엔드포인트로 전송되는 모든 웹훅 요청에 포함됩니다.

변환(Transformations)

변환 기능을 사용하면 웹훅 페이로드를 수정하고 다른 URL로 리디렉션할 수 있습니다. 이 강력한 기능을 통해 다음을 수행할 수 있습니다:
  • 처리 전에 페이로드 구조 수정
  • 콘텐츠에 따라 웹훅을 다른 엔드포인트로 라우팅
  • 페이로드에서 필드 추가 또는 제거
  • 데이터 형식 변환
1

Enable Transformations

사용(Veliable) 스위치를 토글하여 변환 기능을 활성화하세요.
2

Configure Transformation

**변환 편집(Edit transformation)**을 클릭하여 변환 규칙을 정의하세요.
JavaScript를 사용하여 웹훅 페이로드를 변환하고 다른 대상 URL을 지정할 수 있습니다.
3

Test Transformation

테스트 인터페이스를 사용하여 변환이 라이브로 적용되기 전에 올바르게 작동하는지 확인하세요.
변환은 웹훅 전달 성능에 큰 영향을 줄 수 있습니다. 철저히 테스트하고 변환 로직을 간단하고 효율적으로 유지하세요.
변환은 다음과 같은 경우에 특히 유용합니다:
  • 다양한 데이터 형식 간 변환
  • 특정 기준에 따라 이벤트 필터링
  • 페이로드에 계산된 필드 추가
  • 이벤트를 다른 마이크로서비스로 라우팅

웹훅 로그 모니터링

로그 탭은 웹훅 전달 상태에 대한 포괄적인 가시성을 제공하여 이벤트를 효과적으로 모니터링, 디버그 및 관리할 수 있도록 합니다.
Logs

활동 모니터링

활동 탭은 시각적 분석을 통해 웹훅 전달 성능에 대한 실시간 인사이트를 제공합니다.
Activity

이메일 알림

웹훅 상태와 관련된 자동 이메일 알림을 통해 문제를 인지하세요. 웹훅 전달이 실패하거나 엔드포인트의 응답이 끊기면 이메일 알림을 받아 신속하게 문제를 해결하여 통합을 원활하게 유지할 수 있습니다.
Webhook Alerting Settings showing email notifications configuration

이메일 알림 활성화

1

Navigate to Alerting Settings

Dodo Payments 대시보드로 이동하여 **대시보드 → 웹훅 → 알림(Alerting)**으로 이동하세요.
2

Enable Email Notifications

**이메일 알림(Email notifications)**을 켜 웹훅 전달 문제에 대한 알림을 받기 시작하세요.
3

Configure Email Address

웹훅 알림을 받기 원하는 이메일 주소를 입력하세요. 웹훅 전달 이슈 등 통합에 영향을 줄 수 있는 특정 이벤트가 발생하면 이 주소로 알림을 전송합니다.
이메일 알림을 활성화하여 웹훅 전달 문제를 조기에 발견하고 안정적인 통합을 유지하세요. 전달 실패나 엔드포인트 비응답이 발생하면 알림을 받습니다.

클라우드 플랫폼에 배포

웹훅 핸들러를 운영 환경에 배포할 준비가 되셨나요? 인기 클라우드 제공업체별로 플랫폼별 모범 사례를 기반으로 웹훅을 배포할 수 있도록 안내서를 제공합니다.
각 플랫폼 안내서에는 환경 설정, 서명 검증 및 해당 제공업체에 특화된 배포 단계가 포함되어 있습니다.