
주요 기능
Real-time Delivery
Secure by Default
Automatic Retries
Event Filtering
시작하기
- Developer → Webhooks 아래 — Endpoints, Event catalog, Logs, Activity, Settings 탭
- 개별 엔드포인트에서 — delivery 통계, signing secret 및 Replay history가 표시되는 Overview 탭과 Testing, Advanced 탭 및 일괄 재생 작업
- 메시지에서 — Logs 탭에서 열 수 있으며, 엔드포인트를 열지 않고도 각 delivery attempt를 개별적으로 재생할 수 있습니다.
Access Webhook Settings
Create Webhook Endpoint
Enter Endpoint URL or Choose Integration
Select Events to Receive
Create Endpoint
Get Secret Key
Rotate Secret (Optional)
Integration Connectors
직접 webhook receiver를 구축하는 대신 integration connector를 사용하여 webhook 이벤트를 타사 서비스로 바로 라우팅할 수 있습니다. 이를 통해 널리 사용되는 플랫폼을 위한 custom webhook handler를 작성하고 유지 관리할 필요가 없습니다.Connector 작동 방식
connector는 Dodo Payments 이벤트를 대상 서비스가 요구하는 형식으로 변환합니다. 제공해야 하는 세부 정보는 대상에 따라 다릅니다.Connector 설정
엔드포인트를 생성하거나 편집할 때 connector를 선택하면 side sheet에 해당 대상에 맞는 설정 안내가 표시됩니다. 예를 들어 Slack에서 incoming webhook URL을 생성하는 방법이나 Resend API key를 찾는 위치가 안내됩니다. 저장하기 전에 connector transformation test를 실행하여 이벤트가 대상에 맞게 올바르게 변환되는지 확인하세요.구독 이벤트 구성
각 webhook endpoint가 수신할 특정 이벤트를 구성할 수 있습니다.Navigate to Webhook Endpoints
Select Your Endpoint
Open Event Configuration
Browse Event Types
payment, subscription, dispute). 검색창을 사용하면 이름이나 keyword로 특정 이벤트를 빠르게 찾을 수 있습니다.Select Events
- 개별 이벤트 선택(예:
payment.succeeded,payment.failed) - 상위 리소스를 선택하여 관련된 모든 이벤트 수신
- 필요에 따라 특정 이벤트 조합
Save Configuration
이벤트 카탈로그
Developer → Webhooks로 이동하여 Event catalog 탭을 엽니다. 이 탭에는 Dodo Payments가 전송할 수 있는 모든 이벤트 유형이 표시되므로 endpoint를 구독하기 전에 사용 가능한 이벤트를 확인할 수 있습니다. 이벤트를 선택하면 schema와 example payload를 볼 수 있으며, 읽으려는 field의 형식을 확인하는 가장 빠른 방법입니다.Webhook Events Guide
Webhook Delivery
Timeout
webhook에는 connection 및 read operation 모두에 대해 15초 timeout window가 적용됩니다. timeout을 방지하려면 endpoint가 빠르게 응답하도록 하세요.Automatic Retries
webhook delivery가 실패하면 Dodo Payments는 시스템에 과부하가 발생하지 않도록 exponential backoff를 사용해 자동으로 retry합니다.Idempotency
각 webhook event에는 고유한webhook-id header가 포함됩니다. 이 identifier를 사용하여 idempotency를 구현하고 중복 처리를 방지하세요.
Event Ordering
retry 또는 network condition으로 인해 webhook event가 순서대로 도착하지 않을 수 있습니다. 어떤 순서로든 event를 처리할 수 있도록 시스템을 설계하세요.Webhook 보안
webhook의 보안을 유지하려면 항상 payload를 validate하고 HTTPS를 사용하세요.Signature 확인
각 webhook request에는webhook-signature header가 포함됩니다. 이 header는 secret key로 서명된 webhook payload와 timestamp의 HMAC SHA256 signature입니다.
SDK verification (권장)
모든 공식 SDK에는 수신한 webhook을 안전하게 validate하고 parse할 수 있는 built-in helper가 포함되어 있습니다. 다음 두 가지 method를 사용할 수 있습니다.unwrap(): webhook secret key를 사용하여 signature를 verify합니다unsafe_unwrap(): verification 없이 payload를 parse합니다
Manual verification (대안)
SDK를 사용하지 않는 경우 Standard Webhooks spec에 따라 직접 signature를 verify할 수 있습니다.webhook-id,webhook-timestamp및 정확한 raw stringifiedpayload를 마침표(.)로 구분하여 연결해 signed message를 구성합니다.- Dashboard의 webhook secret key를 사용하여 해당 문자열의 HMAC SHA256을 계산합니다.
- 계산한 signature를
webhook-signatureheader와 비교합니다. 일치하면 webhook은 authentic합니다.
소스 IP 주소
웹훅을 인증하는 데 지원되는 방법은 서명 검증입니다. 이를 통해 요청이 웹훅 시크릿으로 서명되었음을 증명할 수 있지만, 네트워크 수준의 확인만으로는 이를 검증할 수 없습니다. 웹훅 전송은 전송 인프라에 속한 소스 IP 주소 풀에서 이루어집니다. 이 풀은 수시로 변경되므로 해당 주소를 통합의 고정된 속성이 아닌 운영상의 세부 정보로 취급하세요. 인프라가 명시적인 allowlist를 요구하는 방화벽 뒤에 있는 경우 다음 사항에 유의하세요:- 주소를 영구적으로 하드코딩하지 마세요. 범위는 시간이 지나면서 추가되고 폐기되며, 오래된 규칙은 전송을 조용히 차단합니다.
- 방화벽을 제한하기 전에 support@dodopayments.com에서 현재 범위를 요청하여 최신 목록을 사용하세요.
- 변경 알림을 확인하세요. 전송 주소가 변경되면 영향을 받는 merchant에게 이메일로 알립니다. 전송이 누락되지 않도록 지정된 날짜 전에 해당 업데이트를 적용하세요.
- 추가하는 네트워크 규칙과 관계없이 서명 검증을 활성화된 상태로 유지하세요.
웹훅에 응답하기
- 웹훅 핸들러는 이벤트 수신을 확인하기 위해
2xx status code를 반환해야 합니다. - 다른 응답은 모두 실패로 처리되며 웹훅이 재시도됩니다.
모범 사례
Use HTTPS endpoints only
Use HTTPS endpoints only
Respond immediately
Respond immediately
200 상태 코드를 반환하세요. 시간 초과를 방지하려면 이벤트를 비동기적으로 처리하세요.Handle duplicate events
Handle duplicate events
webhook-id 헤더를 사용하여 멱등성을 구현하면 동일한 이벤트가 여러 번 처리되어도 부작용 없이 안전하게 처리할 수 있습니다.Secure your webhook secret
Secure your webhook secret
웹훅 페이로드 구조
웹훅 페이로드 구조를 이해하면 이벤트를 올바르게 파싱하고 처리하는 데 도움이 됩니다.요청 형식
헤더
요청 본문
payment.succeeded, subscription.active).페이로드 예시
Event Types
Event Payloads
Handle Payment Failures
payment.failed에 대응하고 거부된 결제를 복구웹훅 테스트
실행 환경으로 전환하기 전에 Dodo Payments 대시보드에서 직접 웹훅 통합을 테스트하여 엔드포인트가 올바르게 작동하는지 확인할 수 있습니다.Navigate to Webhooks
Select Your Endpoint
Open Testing Tab
예시 이벤트 전송
Testing 탭은 수신기를 확인할 수 있도록 이 엔드포인트에 샘플 페이로드를 전송합니다.Select Event Type
payment.succeeded 또는 payment.failed).Send Example
Check Your Endpoint
2xx 상태 코드를 반환했는지 확인하세요.구현 예시
다음은 웹훅 검증 및 처리를 보여 주는 완전한 Express.js 구현 예시입니다:CLI로 웹훅 테스트
Dodo Payments CLI는 터미널을 벗어나지 않고 로컬 개발 중 웹훅을 테스트할 수 있는 두 가지 명령을 제공합니다.로컬에서 실시간 웹훅 수신
테스트 모드 계정의 실제 웹훅 이벤트를 로컬 개발 서버로 실시간 전달하세요:http://localhost:3000/webhook)로 전달합니다. 검증 테스트를 위해 서명 헤더를 포함한 모든 헤더가 그대로 유지됩니다.
dodo login를 실행하고 Test Mode를 선택하세요.모의 웹훅 이벤트 트리거
실제 거래를 생성하지 않고 모든 엔드포인트에 모의 웹훅 페이로드를 전송하세요:CLI Webhook Testing Docs
고급 설정
Advanced 탭에서는 웹훅 엔드포인트 동작을 세밀하게 조정할 수 있는 추가 구성 옵션을 제공합니다.Rate Limiting(Throttling)
시스템에 과부하가 발생하지 않도록 웹훅 이벤트가 엔드포인트로 전달되는 속도를 제어하세요.Open Advanced Tab
Configure Rate Limit
Set Your Limit
사용자 지정 헤더
엔드포인트로 전송되는 모든 웹훅 요청에 사용자 지정 HTTP 헤더를 추가하세요. 인증, 라우팅 또는 메타데이터 추가에 유용합니다.Add Headers
Add Multiple Headers
변환
변환을 사용하면 웹훅의 페이로드를 수정하고 필요한 경우 다른 URL로 리디렉션할 수 있습니다. 이 강력한 기능을 사용하면 다음 작업을 수행할 수 있습니다:- 처리 전에 페이로드 구조 수정
- 콘텐츠에 따라 웹훅을 다른 엔드포인트로 라우팅
- 페이로드에서 필드 추가 또는 제거
- 데이터 형식 변환
Enable Transformations
Configure Transformation
Test Transformation
웹훅 로그 모니터링
Logs 탭에서는 웹훅 전달 상태를 종합적으로 확인할 수 있어 웹훅 이벤트를 효과적으로 모니터링하고 디버깅하며 관리할 수 있습니다.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 전체 웹훅 페이로드
- 응답 코드 및 기간이 포함된 모든 전송 시도
- 각 시도의 타임스탬프
- 엔드포인트에서 반환된 오류 메시지
활동 모니터링
Developer → Webhooks로 이동하여 Activity 탭을 열면 엔드포인트 전반의 전달 성능을 확인할 수 있습니다. Delivery activity는 시간에 따른 시도를 표시하며, 기간에 따라 Attempts per 5 minutes, Attempts per hour 또는 Attempts per day 단위로 그룹화됩니다. 각 막대는 결과별로 나뉘며, 세그먼트에 마우스를 올리면 상태, 시도 횟수 및 전체에서 차지하는 비율이 표시됩니다. 엔드포인트의 Overview 탭에 있는 **Delivery stats (last 24h)**에서는 지난 하루 동안의 동일한 정보를 요약합니다.메시지 재생 및 복구
메시지를 다시 전송하는 방법은 필요한 메시지 수에 따라 달라집니다:- 메시지 하나 — Logs 탭에서 메시지를 열고 시도 항목의 Replay 작업을 사용하세요. 엔드포인트를 열 필요가 없습니다.
- 메시지 범위 — 일괄 모드는 한 번에 하나의 엔드포인트에만 적용되므로 엔드포인트를 여세요.
일괄 재생
Developer → Webhooks에서 엔드포인트를 여세요. 세 가지 모드를 사용할 수 있으며, 각 모드는 해당 엔드포인트에만 적용됩니다. 설정하는 범위는 모드에 따라 다릅니다:Open More Actions
Set the Range
Start the Run
이메일 알림
엔드포인트로의 웹훅 전달이 실패할 때 이메일 알림을 받아 문제가 누적되기 전에 해결하세요.Navigate to Settings Tab
Find Email Alerting
Configure Email Addresses
Save