웹훅 이벤트 가이드

Dodo Payments는 거래, 구독, 환불, 분쟁 및 라이선스 키 관리와 관련된 중요한 이벤트에 대한 실시간 웹훅 알림을 제공합니다. 아래는 이러한 이벤트에 대한 자세한 가이드로, 명확성을 위해 분류되어 있으며, 구현 팁과 고려 사항이 포함되어 있습니다.

결제 이벤트

Event Name	Event Type	Description
Payment Succeeded	`payment.succeeded`	결제가 성공적으로 처리되면 트리거됩니다.
Payment Failed	`payment.failed`	오류, 거절된 카드 또는 기타 문제로 결제 시도가 실패하면 발생합니다.
Payment Processing	`payment.processing`	결제가 현재 처리 중임을 나타냅니다.
Payment Cancelled	`payment.cancelled`	결제가 완료되기 전에 취소되면 트리거됩니다.

환불 이벤트

Event Name	Event Type	Description
Refund Succeeded	`refund.succeeded`	환불이 성공적으로 처리되면 트리거됩니다.
Refund Failed	`refund.failed`	처리 오류 또는 기타 문제로 환불 시도가 실패하면 발생합니다.

분쟁 이벤트

Event Name	Event Type	Description
Dispute Opened	`dispute.opened`	고객이 분쟁을 시작하면 트리거됩니다.
Dispute Expired	`dispute.expired`	분쟁이 해결 없이 만료되었음을 나타냅니다.
Dispute Accepted	`dispute.accepted`	가맹점이 분쟁을 수락하면 트리거됩니다.
Dispute Cancelled	`dispute.cancelled`	고객 또는 시스템에 의해 분쟁이 취소되면 발생합니다.
Dispute Challenged	`dispute.challenged`	가맹점이 분쟁에 이의를 제기하면 트리거됩니다.
Dispute Won	`dispute.won`	가맹점이 분쟁에서 승소했음을 나타냅니다.
Dispute Lost	`dispute.lost`	가맹점이 분쟁에서 패배하면 발생합니다.

구독 이벤트

이벤트 이름	이벤트 유형	설명
구독 활성화	`subscription.active`	구독이 활성화되고 반복 청구가 예약되었음을 나타냅니다.
구독 업데이트	`subscription.updated`	구독 필드가 업데이트될 때 트리거됩니다(폴링 없이 실시간 동기화).
구독 보류	`subscription.on_hold`	갱신에 실패하여 구독이 일시적으로 보류될 때 트리거됩니다.
구독 일시 중지	`subscription.paused`	구독이 일시 중지될 때 트리거됩니다.
구독 일시 중지 해제	`subscription.unpaused`	일시 중지된 구독이 재개될 때 트리거됩니다.
구독 갱신	`subscription.renewed`	구독이 성공적으로 갱신될 때 발생합니다.
구독 플랜 변경	`subscription.plan_changed`	구독이 업그레이드, 다운그레이드되거나 다른 추가 기능으로 수정될 때 트리거됩니다.
구독 결제 수단 업데이트	`subscription.update_payment_method`	구독의 결제 수단이 업데이트될 때 전송됩니다. Subscription 페이로드를 포함합니다.
구독 취소	`subscription.cancelled`	Merchant 또는 Customer가 구독을 취소할 때 트리거됩니다.
구독 실패	`subscription.failed`	구독에 실패했음을 나타냅니다. 즉, mandate를 생성할 수 없었습니다.
구독 만료	`subscription.expired`	구독이 약정 기간의 종료에 도달하여 만료될 때 트리거됩니다.

라이선스 키 이벤트

Event Name	Event Type	Description
License Key Created	`license_key.created`	제품에 대한 새 라이선스 키가 생성되면 트리거됩니다.

권한 부여 이벤트

이벤트 이름	이벤트 유형	설명
Grant Created	`entitlement_grant.created`	고객에게 새로운 권한 부여가 생성됩니다. 라이선스 키 부여는 `delivered`에서 도착합니다. OAuth 기반 부여(Discord, GitHub, Notion)는 `pending`에서 도착합니다.
Grant Delivered	`entitlement_grant.delivered`	권한 이행이 완료되었습니다 — 라이선스 키 발급, 파일 링크 해결, 또는 플랫폼 접근이 허가되었습니다.
Grant Failed	`entitlement_grant.failed`	권한 이행에 실패했습니다; `error_code` 및 `error_message`를 확인하십시오.
Grant Revoked	`entitlement_grant.revoked`	접근이 철회 되었습니다; `revocation_reason`를 확인하십시오 (구독 상태, 환불, 계획 변경, 또는 수동).

자세한 페이로드 스키마, 샘플 이벤트 및 전체 revocation_reason 참조는 Entitlement Grant Webhooks를 참조하세요.

크레딧 이벤트

이벤트 이름	이벤트 유형	설명
크레딧 추가됨	`credit.added`	고객에게 크레딧이 부여될 때 트리거됩니다(구독, 일회성, 추가 기능 또는 API).
크레딧 차감됨	`credit.deducted`	사용량 또는 수동 차감으로 크레딧이 소비될 때 발생합니다.
크레딧 만료됨	`credit.expired`	설정된 만료 기간 후에 사용되지 않은 크레딧이 만료되면 트리거됩니다.
크레딧 이월됨	`credit.rolled_over`	사용되지 않은 크레딧이 주기 종료 시 새로운 부여로 이월될 때 발생합니다.
이월 몰수됨	`credit.rollover_forfeited`	최대 이월 횟수에 도달하여 크레딧이 몰수되면 트리거됩니다.
초과 청구됨	`credit.overage_charged`	잔액이 0 이하로 떨어진 사용량에 대해 초과 요금이 부과될 때 발생합니다.
초과 리셋됨	`credit.overage_reset`	누적된 초과 요금이 리셋될 때 트리거됩니다(예: 새 청구 주기 시작 시).
수동 조정	`credit.manual_adjustment`	수동으로 크레딧이나 차감 조정이 이루어질 때 트리거됩니다.
잔액 부족	`credit.balance_low`	크레딧 잔액이 설정된 임계값 이하로 떨어질 때 트리거됩니다.

복구 이벤트

이벤트 이름	이벤트 유형	설명
Abandoned Checkout Detected	`abandoned_checkout.detected`	60분 후 완료되지 않거나 실패한 결제가 감지될 때 트리거됩니다.
Abandoned Checkout Recovered	`abandoned_checkout.recovered`	고객이 복구 링크를 통해 결제를 완료할 때 발생합니다.

상세한 페이로드 스키마, 필드 설명 및 핸들러 예제는 복구 웹훅을 참조하세요.

차징 이벤트

이벤트 이름	이벤트 유형	설명
Dunning Started	`dunning.started`	보류되거나 취소된 구독에 대해 차징 시도가 시작될 때 트리거됩니다.
Dunning Recovered	`dunning.recovered`	고객이 결제 방법을 업데이트하고 그에 따른 청구가 성공할 때 발생합니다.

자세한 페이로드 스키마, 필드 설명 및 처리기 예제는 Recovery Webhooks를 참조하세요.

지급 이벤트

이 이벤트는 Dodo Payments에서 은행 계좌로 자금이 이동하는 과정을 추적하며, 대시보드에 표시되는 지급 상태를 반영합니다. 페이로드는 GET /payouts의 항목과 동일한 구조를 가진 지급 객체입니다.

이벤트 이름	이벤트 유형	설명
지급 생성	`payout.created`	자동 지급 주기 또는 주기 외 지급에 의해 지급이 생성될 때 트리거됩니다.
지급 처리 중	`payout.in_progress`	지급 예정일이 도래하여 지급 처리가 시작될 때 발생합니다.
지급 보류	`payout.on_hold`	지급이 일시 중지되거나 검토 대상으로 지정될 때 트리거됩니다.
지급 성공	`payout.success`	은행 계좌로의 지급 처리가 성공적으로 완료될 때 발생합니다.
지급 실패	`payout.failed`	지급에 실패할 때 트리거됩니다. 자금과 수수료는 지갑에 다시 적립됩니다.

지급 이벤트가 종료 상태이거나 엄격한 순서로 발생한다고 가정하지 마세요. 은행이 이체를 반환하는 경우 payout.failed가 payout.success 이후에 정상적으로 도착할 수 있으며, 실패한 지급이 나중에 복구되는 경우 payout.success가 payout.failed 이후에 도착할 수 있습니다. 항상 페이로드의 상태를 현재 상태로 처리하세요.

payout.created는 이전에 payout.not_initiated로 전송되었습니다. payout.not_initiated를 기준으로 필터링하는 기존 엔드포인트가 있다면, 계속 일치하도록 필터를 payout.created로 업데이트하세요.

자세한 페이로드 스키마, 필드 설명 및 핸들러 예시는 지급 웹훅을 참조하세요. 이 웹훅 이벤트는 가맹점이 운영을 효과적으로 관리하는 데 필요한 중요한 업데이트를 제공하도록 설계되었습니다. 원활하고 안정적인 기능을 보장하려면 웹훅 통합에서 관련된 각 이벤트에 대해 견고한 핸들러를 구현하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

결제 이벤트

환불 이벤트

분쟁 이벤트

구독 이벤트

라이선스 키 이벤트

권한 부여 이벤트

크레딧 이벤트

복구 이벤트

차징 이벤트

지급 이벤트

​결제 이벤트

​환불 이벤트

​분쟁 이벤트

​구독 이벤트

​라이선스 키 이벤트

​권한 부여 이벤트

​크레딧 이벤트

​복구 이벤트

​차징 이벤트

​지급 이벤트

결제 이벤트

환불 이벤트

분쟁 이벤트

구독 이벤트

라이선스 키 이벤트

권한 부여 이벤트

크레딧 이벤트

복구 이벤트

차징 이벤트

지급 이벤트