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

주요 기능

실시간 전송

이벤트 발생 시 즉각적인 알림 수신

기본적으로 보안

HMAC SHA256 서명 검증 포함

자동 재시도

지수 백오프가 있는 내장 재시도 로직

이벤트 필터링

필요한 이벤트에만 구독

시작하기

1

웹훅 설정 접근하기

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

웹훅 엔드포인트 생성하기

Add Webhook를 클릭하여 새 웹훅 엔드포인트를 생성합니다.
Add Webhook
3

엔드포인트 URL 추가하기

웹훅 이벤트를 수신할 URL을 입력합니다.
4

수신할 이벤트 선택하기

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

비밀 키 가져오기

설정 페이지에서 웹훅 Secret Key을 가져옵니다. 이 키를 사용하여 수신된 웹훅의 진위를 검증합니다.
웹훅 비밀 키를 안전하게 보관하고 클라이언트 측 코드나 공개 저장소에 노출하지 마세요.
6

비밀 키 회전(선택 사항)

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

구독한 이벤트 구성하기

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

이벤트 구성 접근하기

1

웹훅 세부정보로 이동하기

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

엔드포인트 선택하기

구성할 웹훅 엔드포인트를 클릭합니다.
3

이벤트 설정 열기

웹훅 세부정보 페이지에서 “구독한 이벤트” 섹션을 확인할 수 있습니다. 편집 버튼을 클릭하여 이벤트 구독을 수정합니다.

이벤트 구독 관리하기

1

사용 가능한 이벤트 보기

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

검색 및 필터링

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

이벤트 선택하기

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

이벤트 세부정보 검토하기

각 이벤트 옆의 정보 아이콘(ⓘ)에 마우스를 올려 해당 이벤트가 트리거되는 시점에 대한 설명을 확인합니다.
5

구성 저장하기

저장을 클릭하여 변경 사항을 적용하거나 취소를 클릭하여 수정을 버립니다.
모든 이벤트의 선택을 해제하면 웹훅 엔드포인트는 알림을 수신하지 않습니다. 애플리케이션이 제대로 작동하는 데 필요한 이벤트는 최소한 선택해야 합니다.

웹훅 전송

타임아웃

웹훅은 연결 및 읽기 작업 모두에 대해 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. 이벤트 페이로드 형식에 대한 내용은 웹훅 페이로드를 참조하세요.

웹훅에 응답하기

  • 웹훅 핸들러는 이벤트 수신을 확인하기 위해 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
required
이 웹훅 이벤트의 고유 식별자입니다. 멱등성 검사를 위해 사용하세요.
webhook-signature
string
required
웹훅의 진위를 검증하기 위한 HMAC SHA256 서명입니다.
webhook-timestamp
string
required
웹훅이 전송된 Unix 타임스탬프(초 단위)입니다.

요청 본문

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

예제 페이로드

{
  "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

웹훅으로 이동하기

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

엔드포인트 선택하기

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

테스트 탭 열기

테스트 탭을 클릭하여 웹훅 테스트 인터페이스에 접근합니다.

웹훅 테스트하기

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

이벤트 유형 선택하기

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

스키마 및 예제 검토하기

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

테스트 이벤트 전송하기

예제 전송 버튼을 클릭하여 테스트 웹훅을 엔드포인트로 전송합니다.
중요: 테스트 인터페이스를 통해 전송된 실패한 메시지는 재시도되지 않습니다. 이는 테스트 목적으로만 사용됩니다.

테스트 검증하기

1

엔드포인트 확인하기

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

서명 검증하기

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

응답 테스트하기

엔드포인트가 이벤트 수신을 확인하기 위해 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.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
웹훅 핸들러를 철저히 테스트하여 프로덕션 이벤트를 처리하기 전에 대시보드 테스트 인터페이스를 사용하세요. 이는 문제를 조기에 식별하고 수정하는 데 도움이 됩니다.

고급 설정

고급 설정 탭은 웹훅 엔드포인트 동작을 미세 조정하기 위한 추가 구성 옵션을 제공합니다.

속도 제한(스로틀링)

웹훅 이벤트가 엔드포인트에 전달되는 속도를 제어하여 시스템 과부하를 방지합니다.
1

속도 제한 설정 접근하기

고급 탭에서 “속도 제한(스로틀링)” 섹션을 찾습니다.
2

속도 제한 구성하기

편집 버튼을 클릭하여 속도 제한 설정을 수정합니다.
기본적으로 웹훅은 “속도 제한 없음”이 적용되어 있으며, 이벤트는 발생하는 즉시 전달됩니다.
3

제한 설정하기

웹훅 전송 빈도를 제어하고 시스템 과부하를 방지하기 위해 원하는 속도 제한을 구성합니다.
웹훅 핸들러가 이벤트를 처리하는 데 시간이 필요하거나 여러 이벤트를 함께 배치하고 싶을 때 속도 제한을 사용하세요.

사용자 정의 헤더

모든 웹훅 요청에 사용자 정의 HTTP 헤더를 추가합니다. 이는 인증, 라우팅 또는 웹훅 요청에 메타데이터를 추가하는 데 유용합니다.
1

사용자 정의 헤더 추가하기

“사용자 정의 헤더” 섹션에서 사용자 정의 헤더의 을 입력합니다.
2

여러 헤더 추가하기

필요에 따라 추가 사용자 정의 헤더를 추가하려면 + 버튼을 클릭합니다.
3

구성 저장하기

모든 웹훅 요청에 사용자 정의 헤더가 포함됩니다.

변환

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

변환 활성화하기

활성화 스위치를 전환하여 변환 기능을 활성화합니다.
2

변환 구성하기

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

변환 테스트하기

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

웹훅 로그 모니터링

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

활동 모니터링

활동 탭은 시각적 분석을 통해 웹훅 전송 성능에 대한 실시간 통찰력을 제공합니다.
Activity

이메일 알림

웹훅 상태에 대한 자동 이메일 알림으로 정보를 유지하세요. 웹훅 전송이 실패하거나 엔드포인트가 응답하지 않기 시작하면 이메일 알림을 받아 문제를 신속하게 해결하고 통합을 원활하게 유지할 수 있습니다.
Webhook Alerting Settings showing email notifications configuration

이메일 알림 활성화하기

1

알림 설정으로 이동하기

Dodo Payments 대시보드로 이동하여 대시보드 → 웹훅 → 알림으로 이동합니다.
2

이메일 알림 활성화하기

이메일 알림을 켜서 웹훅 전송 문제에 대한 알림을 받기 시작합니다.
3

이메일 주소 구성하기

웹훅 알림을 받을 이메일 주소를 입력합니다. 특정 이벤트가 웹훅 설정에서 발생할 때 이 주소로 알림을 전송합니다. 예를 들어, 통합에 영향을 미칠 수 있는 전송 문제와 같은 경우입니다.
이메일 알림을 활성화하여 웹훅 전송 문제를 조기에 발견하고 신뢰할 수 있는 통합을 유지하세요. 전송이 실패하거나 엔드포인트가 응답하지 않을 때 알림을 받게 됩니다.

클라우드 플랫폼에 배포하기

웹훅 핸들러를 프로덕션에 배포할 준비가 되셨나요? 우리는 각 플랫폼에 대한 모범 사례와 함께 인기 있는 클라우드 제공업체에 웹훅을 배포하는 데 도움이 되는 플랫폼별 가이드를 제공합니다.
각 플랫폼 가이드에는 환경 설정, 서명 검증 및 해당 제공업체에 특정한 배포 단계가 포함되어 있습니다.