웹훅은 Dodo Payments 계정에서 특정 이벤트가 발생할 때 실시간 알림을 제공합니다. 웹훅을 사용하여 워크플로를 자동화하고, 데이터베이스를 업데이트하며, 알림을 전송하고, 시스템을 동기화 상태로 유지하세요.
주요 기능
Real-time Delivery
이벤트 발생 시 즉시 알림 수신
Secure by Default
HMAC SHA256 서명 검증 포함
Automatic Retries
지수 백오프가 적용된 내장 재시도 로직
Event Filtering
필요한 이벤트만 구독
시작하기
Access Webhook Settings
DodoPayments 대시보드로 이동하여 Settings > Webhooks로 이동합니다.
Create Webhook Endpoint
새 웹훅 엔드포인트를 만들려면 Add Webhook를 클릭합니다. Add Endpoint URL
웹훅 이벤트를 수신할 URL을 입력하세요.
Select Events to Receive
이벤트 목록에서 선택하여 웹훅 엔드포인트가 수신할 특정 이벤트를 선택하세요.선택한 이벤트만 엔드포인트에 웹훅을 트리거하여 불필요한 트래픽과 처리를 방지할 수 있습니다.
Get Secret Key
설정 페이지에서 웹훅 Secret Key를 가져오세요. 수신한 웹훅의 진위를 확인할 때 이 값을 사용합니다.웹훅 비밀 키를 안전하게 보관하고 클라이언트 측 코드나 공개 저장소에 절대 노출하지 마세요.
Rotate Secret (Optional)
필요한 경우 보안을 강화하기 위해 웹훅 비밀을 교체할 수 있습니다. 웹훅 설정에서 비밀 교체(Rotate Secret) 버튼을 클릭하세요.비밀을 교체하면 기존 비밀은 만료되고 새 비밀로 대체됩니다. 이전 비밀은 다음 24시간 동안만 유효합니다. 이후에는 이전 비밀로 검증을 시도하면 실패합니다.
현재 비밀이 유출되었다고 의심되면 주기적으로 또는 즉시 비밀을 교체하세요.
구독한 이벤트 구성하기
각 웹훅 엔드포인트에 대해 수신할 특정 이벤트를 구성할 수 있습니다.
이벤트 구성 접근하기
Navigate to Webhook Details
Dodo Payments 대시보드로 이동하여 Settings > Webhooks로 이동하세요.
Select Your Endpoint
구성하려는 웹훅 엔드포인트를 클릭하세요.
Open Event Settings
웹훅 세부 정보 페이지에서 “Subscribed events” 섹션을 확인하세요. 이벤트 구독을 수정하려면 편집(Edit) 버튼을 클릭합니다.
이벤트 구독 관리하기
View Available Events
인터페이스에는 모든 사용 가능한 웹훅 이벤트가 계층 구조로 구성되어 표시됩니다. 이벤트는 카테고리별로 그룹화됩니다(예: dispute, payment, subscription).
Search and Filter
검색 표시줄을 사용하여 이벤트 이름이나 키워드를 입력하면 특정 이벤트를 빠르게 찾을 수 있습니다.
Select Events
수신하려는 이벤트 옆의 체크박스를 확인하세요. 다음을 수행할 수 있습니다:
- 개별 하위 이벤트 선택 (예:
dispute.accepted, dispute.challenged)
- 관련된 모든 하위 이벤트를 수신하기 위해 상위 이벤트 선택
- 필요에 따라 특정 이벤트를 조합하여 선택
Review Event Details
각 이벤트 옆 정보 아이콘(ⓘ) 위에 커서를 올리면 해당 이벤트가 언제 트리거되는지 설명이 표시됩니다.
Save Configuration
**저장(Save)**을 클릭하여 변경 사항을 적용하거나 **취소(Cancel)**를 클릭하여 수정을 취소하세요.
모든 이벤트를 선택 취소하면 웹훅 엔드포인트는 알림을 받지 않습니다. 애플리케이션이 제대로 작동하기 위해 필요한 이벤트는 최소한 하나 이상 선택되어 있는지 확인하세요.
웹훅 전송
타임아웃
웹훅은 연결 및 읽기 작업 모두에 대해 15초 타임아웃 창을 가집니다. 타임아웃을 피하기 위해 엔드포인트가 빠르게 응답하도록 하세요.
웹훅을 비동기로 처리하려면 수신 즉시 200 상태 코드를 반환하여 수신을 확인한 다음 실제 처리는 백그라운드에서 수행하세요.
자동 재시도
웹훅 전송이 실패하면 Dodo Payments는 시스템이 과부하되지 않도록 지수 백오프를 사용하여 자동으로 재시도합니다.
| 시도 | 지연 | 설명 |
|---|
| 1 | 즉시 | 첫 번째 재시도는 즉시 발생 |
| 2 | 5초 | 두 번째 시도는 짧은 지연 후 |
| 3 | 5분 | 세 번째 시도는 증가된 백오프와 함께 |
| 4 | 30분 | 네 번째 시도는 계속된 백오프 |
| 5 | 2시간 | 다섯 번째 시도는 연장된 지연과 함께 |
| 6 | 5시간 | 여섯 번째 시도는 더 긴 지연과 함께 |
| 7 | 10시간 | 일곱 번째 시도는 최대 지연과 함께 |
| 8 | 10시간 | 최종 시도 - 실패한 경우 웹훅이 실패로 표시됨 |
웹훅 이벤트당 최대 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 사양에 따라 서명을 직접 검증할 수 있습니다:
webhook-id, webhook-timestamp, 정확한 원시 문자열화된 payload를 마침표( .)로 구분하여 서명된 메시지를 구성합니다.
- 대시보드에서 가져온 웹훅 비밀 키를 사용하여 해당 문자열의 HMAC SHA256을 계산합니다.
- 계산된 서명과
webhook-signature 헤더를 비교합니다. 일치하면 웹훅이 인증된 것입니다.
웹훅에 응답하기
- 이벤트를 수신했음을 확인하려면 웹훅 핸들러가
2xx status code를 반환해야 합니다.
- 그 외의 응답은 실패로 간주되며 웹훅은 재시도됩니다.
모범 사례
웹훅 엔드포인트에는 항상 HTTPS URL을 사용하세요. HTTP 엔드포인트는 중간자 공격에 취약하며 웹훅 데이터를 노출할 수 있습니다.
webhook-id 헤더를 사용하여 멱등성을 구현하면 동일한 이벤트를 여러 번 안전하게 처리할 수 있습니다.
Secure your webhook secret
웹훅 비밀은 환경 변수나 시크릿 관리자 등 안전한 장소에 보관하세요. 절대로 버전 관리에 비밀을 커밋하지 마세요.
웹훅 페이로드 구조
웹훅 페이로드 구조를 이해하면 이벤트를 올바르게 구문 분석하고 처리하는 데 도움이 됩니다.
요청 형식
POST /your-webhook-url
Content-Type: application/json
이 웹훅 이벤트의 고유 식별자입니다. 멱등성 검사에 사용하세요.
웹훅 진위를 확인하기 위한 HMAC SHA256 서명입니다.
웹훅이 전송된 시점의 유닉스 타임스탬프(초 단위)입니다.
요청 본문
당신의 Dodo Payments 비즈니스 식별자입니다.
이 웹후크를 트리거한 이벤트 유형(예: payment.succeeded, subscription.active).
이벤트가 발생한 시점의 ISO 8601 형식 타임스탬프입니다.
이벤트에 대한 자세한 정보를 포함하는 이벤트별 페이로드입니다.표시 Data object properties
리소스 유형: Payment, Subscription, Refund, Dispute 또는 LicenseKey.
추가 필드는 이벤트 유형에 따라 다릅니다. 전체 스키마는 이벤트별 문서를 참조하세요.
예제 페이로드
{
"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 대시보드에서 웹훅 통합을 직접 테스트하여 엔드포인트가 올바르게 작동하는지 확인할 수 있습니다.
테스트 인터페이스 접근하기
Navigate to Webhooks
Dodo Payments 대시보드로 이동하여 Settings > Webhooks로 이동하세요.
Select Your Endpoint
웹훅 엔드포인트를 클릭하여 세부 정보 페이지에 접근하세요.
Open Testing Tab
테스트 탭을 클릭하여 웹훅 테스트 인터페이스에 접근하세요.
웹훅 테스트하기
테스트 인터페이스는 웹훅 엔드포인트를 테스트하는 포괄적인 방법을 제공합니다:
Select Event Type
드롭다운 메뉴를 사용하여 테스트할 특정 이벤트 유형을 선택하세요(예: payment.succeeded, payment.failed 등).드롭다운에는 엔드포인트가 수신할 수 있는 모든 웹훅 이벤트 유형이 포함됩니다.
Review Schema and Example
인터페이스에는 선택한 이벤트 유형에 대한 스키마(데이터 구조)와 예시(샘플 페이로드)가 모두 표시됩니다.
Send Test Event
예시 전송(Send Example) 버튼을 클릭하여 테스트 웹훅을 엔드포인트로 전송하세요.중요: 테스트 인터페이스를 통해 전송된 실패한 메시지는 재시도되지 않습니다. 이 기능은 테스트용입니다.
테스트 검증하기
Check Your Endpoint
테스트 이벤트가 수신되었는지 확인하려면 웹훅 엔드포인트 로그를 모니터링하세요.
Verify Signature
테스트 페이로드로 서명 검증이 올바르게 작동하는지 확인하세요.
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는 터미널을 벗어나지 않고도 로컬 개발 중 웹훅을 테스트할 수 있는 두 가지 명령을 제공합니다.
로컬에서 실시간 웹훅 수신
테스트 모드 계정의 실제 웹훅 이벤트를 로컬 개발 서버로 실시간 전송하려면:
CLI는 Dodo Payments에 WebSocket 연결을 열어 모든 웹훅 이벤트를 로컬 엔드포인트(예: http://localhost:3000/webhook)로 전달하며, 서명 검증 테스트를 위한 서명 헤더를 포함한 모든 헤더를 그대로 유지합니다.
리스너는 테스트 모드 API 키에서만 작동합니다. 이 명령을 사용하기 전에 dodo login를 실행하여 테스트 모드를 선택하세요.
모의 웹훅 이벤트 트리거
실제 거래를 만들지 않고도 모의 웹훅 페이로드를 모든 엔드포인트로 전송하려면:
이 인터랙티브 도구를 사용하면 지원되는 22개 이벤트 유형 모두를 선택할 수 있으며, 실제 같은 모의 페이로드를 엔드포인트로 전송합니다. 한 세션에서 여러 이벤트를 테스트할 수 있도록 반복 실행됩니다.
dodo wh trigger에서 생성된 모의 웹훅 페이로드는 서명되지 않습니다. 테스트 중에만 웹훅 핸들러에서 unwrap() 대신 unsafe_unwrap()를 사용하세요.
CLI Webhook Testing Docs
전체 CLI 웹훅 테스트 설명서를 참조하세요
고급 설정
고급 설정 탭은 웹훅 엔드포인트 동작을 세부 조정할 수 있는 추가 구성 옵션을 제공합니다.
속도 제한(스로틀링)
시스템 과부하를 방지하기 위해 웹훅 이벤트가 엔드포인트로 전달되는 속도를 제어하세요.
Access Rate Limit Settings
고급(Advanced) 탭에서 “속도 제한(스로틀링)” 섹션을 찾으세요.
Configure Rate Limit
편집(Edit) 버튼을 클릭하여 속도 제한 설정을 수정하세요.기본적으로 웹훅에는 “제한 없음(No rate limit)“이 적용되어 이벤트가 발생하는 즉시 전달됩니다.
Set Limits
원하는 속도 제한을 구성하여 웹훅 전달 빈도를 제어하고 시스템 과부하를 방지하세요.
이벤트를 처리하는 시간이 필요하거나 여러 이벤트를 함께 배치 처리하려는 경우에는 속도 제한을 활용하세요.
커스텀 헤더
웹훅 요청에 커스텀 HTTP 헤더를 추가하세요. 이는 인증, 라우팅 또는 메타데이터 추가에 유용합니다.
Add Custom Header
“커스텀 헤더” 섹션에서 커스텀 헤더의 키와 값을 입력하세요.
Add Multiple Headers
+ 버튼을 클릭하여 필요한 만큼 커스텀 헤더를 추가하세요.
Save Configuration
커스텀 헤더는 이 엔드포인트로 전송되는 모든 웹훅 요청에 포함됩니다.
변환 기능을 사용하면 웹훅 페이로드를 수정하고 다른 URL로 리디렉션할 수 있습니다. 이 강력한 기능을 통해 다음을 수행할 수 있습니다:
- 처리 전에 페이로드 구조 수정
- 콘텐츠에 따라 웹훅을 다른 엔드포인트로 라우팅
- 페이로드에서 필드 추가 또는 제거
- 데이터 형식 변환
Enable Transformations
사용(Veliable) 스위치를 토글하여 변환 기능을 활성화하세요.
Configure Transformation
**변환 편집(Edit transformation)**을 클릭하여 변환 규칙을 정의하세요.JavaScript를 사용하여 웹훅 페이로드를 변환하고 다른 대상 URL을 지정할 수 있습니다.
Test Transformation
테스트 인터페이스를 사용하여 변환이 라이브로 적용되기 전에 올바르게 작동하는지 확인하세요.
변환은 웹훅 전달 성능에 큰 영향을 줄 수 있습니다. 철저히 테스트하고 변환 로직을 간단하고 효율적으로 유지하세요.
변환은 다음과 같은 경우에 특히 유용합니다:
- 다양한 데이터 형식 간 변환
- 특정 기준에 따라 이벤트 필터링
- 페이로드에 계산된 필드 추가
- 이벤트를 다른 마이크로서비스로 라우팅
웹훅 로그 모니터링
로그 탭은 웹훅 전달 상태에 대한 포괄적인 가시성을 제공하여 이벤트를 효과적으로 모니터링, 디버그 및 관리할 수 있도록 합니다.
활동 모니터링
활동 탭은 시각적 분석을 통해 웹훅 전달 성능에 대한 실시간 인사이트를 제공합니다.
이메일 알림
웹훅 상태와 관련된 자동 이메일 알림을 통해 문제를 인지하세요. 웹훅 전달이 실패하거나 엔드포인트의 응답이 끊기면 이메일 알림을 받아 신속하게 문제를 해결하여 통합을 원활하게 유지할 수 있습니다.
이메일 알림 활성화
Navigate to Alerting Settings
Dodo Payments 대시보드로 이동하여 **대시보드 → 웹훅 → 알림(Alerting)**으로 이동하세요.
Enable Email Notifications
**이메일 알림(Email notifications)**을 켜 웹훅 전달 문제에 대한 알림을 받기 시작하세요.
Configure Email Address
웹훅 알림을 받기 원하는 이메일 주소를 입력하세요. 웹훅 전달 이슈 등 통합에 영향을 줄 수 있는 특정 이벤트가 발생하면 이 주소로 알림을 전송합니다.
이메일 알림을 활성화하여 웹훅 전달 문제를 조기에 발견하고 안정적인 통합을 유지하세요. 전달 실패나 엔드포인트 비응답이 발생하면 알림을 받습니다.
클라우드 플랫폼에 배포
웹훅 핸들러를 운영 환경에 배포할 준비가 되셨나요? 인기 클라우드 제공업체별로 플랫폼별 모범 사례를 기반으로 웹훅을 배포할 수 있도록 안내서를 제공합니다.
각 플랫폼 안내서에는 환경 설정, 서명 검증 및 해당 제공업체에 특화된 배포 단계가 포함되어 있습니다.