Webhooks는 Dodo Payments 계정에서 특정 이벤트가 발생할 때 실시간 알림을 제공합니다. Webhooks를 사용하여 워크플로를 자동화하고, 데이터베이스를 업데이트하고, 알림을 전송하며, 시스템을 동기화된 상태로 유지할 수 있습니다.
주요 기능
Real-time Delivery 이벤트가 발생하면 즉시 알림 수신
Secure by Default HMAC SHA256 서명 검증 포함
Automatic Retries 지수 백오프를 적용한 기본 재시도 로직
Event Filtering 필요한 이벤트만 구독
시작하기
Access Webhook Settings
DodoPayments Dashboard로 이동한 다음 Developer > Webhooks로 이동합니다.
Create Webhook Endpoint
새 webhook endpoint를 생성하려면 Add Webhook를 클릭합니다.
Add Endpoint URL
webhook 이벤트를 수신할 URL을 입력합니다.
Select Events to Receive
이벤트 목록에서 webhook endpoint가 수신할 특정 이벤트를 선택합니다. 선택한 이벤트만 endpoint로 webhook을 트리거하므로 불필요한 트래픽과 처리를 줄일 수 있습니다.
Get Secret Key
설정 페이지에서 webhook Secret Key를 가져옵니다. 수신한 webhook의 진위를 확인할 때 사용합니다. webhook secret key를 안전하게 보관하고 client-side code나 public repository에 절대 노출하지 마세요.
Rotate Secret (Optional)
필요한 경우 보안을 강화하기 위해 webhook secret을 교체할 수 있습니다. webhook 설정에서 Rotate Secret 버튼을 클릭합니다. secret을 교체하면 기존 secret이 만료 되고 새 secret으로 대체 됩니다. 이전 secret은 이후 24시간 동안만 유효합니다. 그 후 이전 secret으로 검증을 시도하면 실패합니다.
secret이 유출되었다고 의심되는 경우 또는 정기적으로 secret rotation을 사용하세요.
구독 이벤트 구성
각 webhook endpoint에서 수신할 특정 이벤트를 구성할 수 있습니다.
이벤트 구성에 액세스
Navigate to Webhook Details
Dodo Payments Dashboard로 이동한 다음 Developer > Webhooks로 이동합니다.
Select Your Endpoint
구성하려는 webhook endpoint를 클릭합니다.
Open Event Settings
webhook details 페이지에서 “Subscribed events” 섹션을 찾습니다. 이벤트 구독을 수정하려면 Edit 버튼을 클릭합니다.
이벤트 구독 관리
View Available Events
인터페이스에는 사용 가능한 모든 webhook 이벤트가 계층 구조로 표시됩니다. 이벤트는 카테고리별로 그룹화됩니다(예: dispute, payment, subscription).
Search and Filter
검색창에 이벤트 이름이나 키워드를 입력하여 특정 이벤트를 빠르게 찾습니다.
Select Events
수신하려는 이벤트 옆의 확인란을 선택합니다. 다음 작업을 수행할 수 있습니다.
개별 하위 이벤트 선택(예: dispute.accepted, dispute.challenged)
상위 이벤트를 선택하여 관련된 모든 하위 이벤트 수신
필요에 따라 특정 이벤트 조합
Review Event Details
각 이벤트 옆의 정보 아이콘(ⓘ) 위에 마우스를 올리면 해당 이벤트가 트리거되는 시점에 대한 설명을 볼 수 있습니다.
Save Configuration
변경 사항을 적용하려면 Save , 수정 사항을 취소하려면 Cancel 을 클릭합니다.
모든 이벤트를 선택 해제하면 webhook endpoint는 알림을 수신하지 않습니다. 애플리케이션이 정상적으로 작동하는 데 필요한 이벤트를 하나 이상 선택해야 합니다.
Webhook 전송
시간 초과
Webhook에는 connection 및 read 작업 모두에 대해 15초의 시간 초과 창 이 적용됩니다. 시간 초과를 방지하려면 endpoint가 신속하게 응답하도록 하세요.
Webhook을 비동기적으로 처리하려면 200 status code로 수신을 즉시 확인한 다음 백그라운드에서 실제 처리를 수행합니다.
자동 재시도
webhook 전송에 실패하면 Dodo Payments 시스템에 과부하가 발생하지 않도록 지수 백오프 방식으로 자동 재시도합니다.
webhook 이벤트당 최대 8회 재시도 됩니다. 예를 들어 webhook이 성공하기 전에 세 번 실패하면 전체 전송 시간은 첫 번째 시도부터 약 35분 5초입니다.
Dodo Payments dashboard를 사용하면 언제든 개별 메시지를 수동으로 재시도하거나 실패한 모든 메시지를 일괄 복구할 수 있습니다.
멱등성
각 webhook 이벤트에는 고유한 webhook-id header가 포함됩니다. 이 식별자를 사용하여 멱등성을 구현하고 중복 처리를 방지하세요.
항상 멱등성 검사를 구현하세요. 재시도로 인해 동일한 이벤트를 여러 번 수신할 수 있습니다.
이벤트 순서
재시도 또는 네트워크 상태로 인해 webhook 이벤트가 순서 없이 도착할 수 있습니다. 어떤 순서로든 이벤트를 처리할 수 있도록 시스템을 설계하세요.
webhook 이벤트가 원래 생성된 시점과 관계없이 전송 시점의 최신 payload 를 수신합니다.
Webhook 보안
Webhook의 보안을 보장하려면 항상 payload를 검증하고 HTTPS를 사용하세요.
서명 검증
각 webhook request에는 webhook-signature header가 포함됩니다. 이 header는 secret key로 서명된 webhook payload 및 timestamp의 HMAC SHA256 signature입니다.
SDK 검증(권장)
모든 공식 SDK에는 수신 webhook을 안전하게 검증하고 파싱할 수 있는 기본 helper가 포함되어 있습니다. 다음 두 가지 method를 사용할 수 있습니다.
unwrap(): webhook secret key를 사용하여 signature를 검증합니다
unsafe_unwrap(): 검증 없이 payload를 파싱합니다
Dodo Payments client를 초기화할 때 DODO_PAYMENTS_WEBHOOK_KEY를 통해 webhook secret을 제공합니다.
수동 검증(대안)
SDK를 사용하지 않는 경우 Standard Webhooks spec에 따라 직접 signature를 검증할 수 있습니다.
webhook-id, webhook-timestamp 및 정확한 원시 문자열화 payload를 마침표(.)로 연결하여 서명된 메시지를 구성합니다.
Dashboard의 webhook secret key를 사용하여 해당 문자열의 HMAC SHA256을 계산합니다.
계산된 signature를 webhook-signature header와 비교합니다. 일치하면 webhook은 진본입니다.
Webhook 응답
webhook handler는 이벤트 수신을 확인하기 위해 2xx status code를 반환해야 합니다.
그 외의 모든 response는 실패로 처리되며 webhook이 재시도됩니다.
모범 사례
webhook endpoint에는 항상 HTTPS URL을 사용하세요. HTTP endpoint는 man-in-the-middle attack에 취약하며 webhook data를 노출합니다.
webhook-id header를 사용하여 멱등성을 구현하고 동일한 이벤트를 부작용 없이 여러 번 안전하게 처리하세요.
Secure your webhook secret
환경 변수 또는 secrets manager를 사용하여 webhook secret을 안전하게 저장하세요. secret을 version control에 절대 commit하지 마세요.
Webhook Payload 구조
Webhook payload 구조를 이해하면 이벤트를 올바르게 파싱하고 처리할 수 있습니다.
Request 형식
이 webhook 이벤트의 고유 식별자입니다. 멱등성 검사에 사용하세요.
webhook의 진위를 확인하기 위한 HMAC SHA256 signature입니다.
webhook이 전송된 시점의 Unix timestamp(초 단위)입니다.
Request Body
Dodo Payments business identifier입니다.
이 webhook을 트리거한 이벤트 유형입니다(예: payment.succeeded, subscription.active).
이벤트가 발생한 시점의 ISO 8601 형식 timestamp입니다.
이벤트에 대한 상세 정보를 포함하는 이벤트별 payload입니다. 표시 Data object properties
리소스 유형입니다. 다음 중 하나입니다: Payment, Subscription, Refund, Dispute, LicenseKey, CreditLedgerEntry, CreditBalanceLow, AbandonedCheckout, DunningAttempt 또는 EntitlementGrant입니다.
추가 field는 이벤트 유형에 따라 달라집니다. 전체 schema는 이벤트별 문서를 참조하세요.
Payload 예시
Event Types 사용 가능한 모든 webhook 이벤트 유형 탐색
Event Payloads 각 이벤트의 상세 payload schema 확인
Handle Payment Failures payment.failed에 대응하고 거부된 payment 복구
Webhooks 테스트
실제 운영을 시작하기 전에 Dodo Payments dashboard에서 webhook integration을 직접 테스트하여 endpoint가 올바르게 작동하는지 확인할 수 있습니다.
테스트 인터페이스에 액세스
Navigate to Webhooks
Dodo Payments Dashboard로 이동한 다음 Developer > Webhooks로 이동합니다.
Select Your Endpoint
webhook endpoint를 클릭하여 details 페이지로 이동합니다.
Open Testing Tab
webhook testing interface에 액세스하려면 Testing 탭을 클릭합니다.
Webhook 테스트
테스트 인터페이스는 webhook endpoint를 테스트할 수 있는 종합적인 방법을 제공합니다.
Select Event Type
dropdown menu에서 테스트할 특정 이벤트 유형을 선택합니다(예: payment.succeeded, payment.failed 등). dropdown에는 endpoint가 수신할 수 있는 모든 webhook 이벤트 유형이 포함됩니다.
Review Schema and Example
인터페이스에는 선택한 이벤트 유형의 Schema (data structure)와 Example (sample payload)이 모두 표시됩니다.
Send Test Event
Send Example 버튼을 클릭하여 endpoint로 test webhook을 전송합니다.중요 : testing interface를 통해 전송된 실패한 message는 재시도되지 않습니다. 이 기능은 테스트 전용입니다.
테스트 확인
Check Your Endpoint
test event가 수신되었는지 확인하려면 webhook endpoint log를 모니터링합니다.
Verify Signature
test payload에서 signature verification이 올바르게 작동하는지 확인합니다.
Test Response
수신을 확인하기 위해 endpoint가 2xx status code를 반환하는지 확인합니다.
구현 예시
다음은 webhook verification 및 handling을 보여주는 완전한 Express.js 구현입니다.
production event를 처리하기 전에 dashboard testing interface를 사용하여 webhook handler를 충분히 테스트하세요. 이를 통해 문제를 조기에 식별하고 해결할 수 있습니다.
CLI로 Webhooks 테스트
Dodo Payments CLI 는 terminal을 벗어나지 않고 local development 중 webhook을 테스트할 수 있는 두 가지 command를 제공합니다.
로컬에서 실시간 Webhooks 수신
test mode account에서 local development server로 실제 webhook event를 실시간 전달합니다.
CLI는 Dodo Payments에 WebSocket connection을 열고 모든 webhook event를 local endpoint(예: http://localhost:3000/webhook)로 전달합니다. verification testing을 위해 signature header를 포함한 모든 header가 유지됩니다.
listener는 test mode API key에서만 작동합니다. 이 command를 사용하기 전에 dodo login를 실행하고 Test Mode를 선택하세요.
Mock Webhook 이벤트 트리거
실제 transaction을 생성하지 않고 모든 endpoint로 mock webhook payload를 전송합니다.
이 interactive tool을 사용하면 지원되는 모든 이벤트 유형 중에서 선택하고 현실적인 mock payload를 endpoint로 전송할 수 있습니다. 한 session에서 여러 이벤트를 테스트할 수 있도록 반복 실행됩니다.
dodo wh trigger의 mock webhook payload에는 signature가 없습니다. 테스트 중에만 webhook handler에서 unwrap() 대신 unsafe_unwrap()를 사용하세요.
CLI Webhook Testing Docs 전체 CLI webhook testing documentation 보기
고급 설정
Advanced Settings 탭은 webhook endpoint 동작을 세부 조정할 수 있는 추가 configuration option을 제공합니다.
Rate Limiting(Throttling)
시스템 과부하를 방지하도록 webhook event가 endpoint로 전달되는 속도를 제어합니다.
Access Rate Limit Settings
Advanced 탭에서 “Rate Limit (throttling)” 섹션을 찾습니다.
Configure Rate Limit
rate limit 설정을 수정하려면 Edit 버튼을 클릭합니다. 기본적으로 webhook에는 “No rate limit”이 적용되므로 이벤트가 발생하는 즉시 전달됩니다.
Set Limits
webhook delivery frequency를 제어하고 system overload를 방지하도록 원하는 rate limit을 구성합니다.
webhook handler가 이벤트를 처리할 시간이 필요하거나 여러 이벤트를 함께 batch 처리하려는 경우 rate limiting을 사용하세요.
endpoint로 전송되는 모든 webhook request에 custom HTTP header를 추가합니다. authentication, routing 또는 webhook request에 metadata를 추가할 때 유용합니다.
Add Custom Header
“Custom Headers” 섹션에서 custom header의 Key 와 Value 를 입력합니다.
Add Multiple Headers
필요한 만큼 custom header를 추가하려면 + 버튼을 클릭합니다.
Save Configuration
custom header는 이 endpoint로 전송되는 모든 webhook request에 포함됩니다.
Transformations를 사용하면 webhook payload를 수정하고 다른 URL로 redirect할 수 있습니다. 이 강력한 기능으로 다음 작업을 수행할 수 있습니다.
처리하기 전에 payload 구조 수정
content에 따라 webhook을 다른 endpoint로 route
payload에서 field 추가 또는 제거
data 형식 변환
Enable Transformations
transformation 기능을 활성화하려면 Enabled switch를 켭니다.
Configure Transformation
transformation rule을 정의하려면 Edit transformation 을 클릭합니다. JavaScript를 사용하여 webhook payload를 변환하고 다른 target URL을 지정할 수 있습니다.
Test Transformation
실제 운영을 시작하기 전에 testing interface를 사용하여 transformation이 올바르게 작동하는지 확인합니다.
Transformation은 webhook delivery performance에 큰 영향을 줄 수 있습니다. 충분히 테스트하고 transformation logic을 간단하고 효율적으로 유지하세요.
Transformation은 특히 다음 작업에 유용합니다.
서로 다른 data 형식 간 변환
특정 criteria에 따른 이벤트 filtering
payload에 computed field 추가
이벤트를 서로 다른 microservice로 routing
Webhook Log 모니터링
Logs 탭은 webhook delivery status를 종합적으로 확인할 수 있도록 하여 webhook event를 효과적으로 모니터링, debug 및 관리할 수 있습니다.
Activity 모니터링
Activity 탭은 visual analytics를 통해 webhook delivery performance에 대한 실시간 insight를 제공합니다.
Email Alerts
자동 email notification으로 webhook 상태를 확인하세요. webhook delivery가 실패하기 시작하거나 endpoint가 응답하지 않으면 email alert를 받아 문제를 신속하게 해결하고 integration을 원활하게 유지할 수 있습니다.
Email Alerts 활성화
Navigate to Alerting Settings
Dodo Payments Dashboard로 이동한 다음 Dashboard → Webhooks → Alerting 으로 이동합니다.
Enable Email Notifications
webhook delivery issue에 대한 alert를 받으려면 Email notifications 를 켭니다.
Configure Email Address
webhook alert를 받을 email address를 입력합니다. webhook setup에서 integration에 영향을 줄 수 있는 delivery issue와 같은 특정 이벤트가 발생하면 이 address로 notification을 전송합니다.
webhook delivery problem을 조기에 파악하고 안정적인 integration을 유지하려면 email alert를 활성화하세요. delivery가 실패하거나 endpoint가 응답하지 않게 되면 notification을 받습니다.
webhook handler를 production에 배포할 준비가 되었나요? 인기 있는 cloud provider에 webhook을 배포할 수 있도록 각 platform의 모범 사례와 함께 platform별 guide를 제공합니다.
Vercel serverless function을 사용하여 Vercel에 webhook 배포
Cloudflare Workers Cloudflare의 edge network에서 webhook 실행
Supabase Edge Functions webhook을 Supabase와 integration
Netlify Functions Netlify serverless function으로 webhook 배포
각 platform guide에는 해당 provider에 맞는 environment setup, signature verification 및 deployment step이 포함되어 있습니다.
관련 API Reference
Create Webhook webhook endpoint를 programmatically 생성하고 구성하기 위한 API reference
List Webhooks webhook endpoint를 검색하고 관리하기 위한 API reference