Webhook Events Guide

Dodo Payments는 payment, subscription, dispute, payout, credit 또는 license key lifecycle의 각 단계에서 webhook event를 발생시킵니다. 이 페이지에는 리소스별 모든 event가 나와 있습니다. 자세한 payload schema와 handler 예시는 아래에 링크된 리소스별 페이지를 참조하세요.

Payment Events

Event	발생 시점
`payment.succeeded`	payment가 성공적으로 처리될 때
`payment.failed`	카드 거절, 잔액 부족 또는 기타 오류로 payment 시도가 실패할 때
`payment.processing`	payment가 처리 중일 때
`payment.cancelled`	완료되기 전에 payment가 취소될 때

전체 payload schema는 Payment Webhooks를 참조하세요.

Refund Events

Event	발생 시점
`refund.succeeded`	refund가 성공적으로 처리될 때
`refund.failed`	처리 오류 또는 기타 문제로 refund 시도가 실패할 때

전체 payload schema는 Refund Webhooks를 참조하세요.

Dispute Events

Event	발생 시점
`dispute.opened`	cardholder가 payment에 대해 dispute를 제기할 때
`dispute.challenged`	dispute에 이의를 제기하기 위한 증거가 제출될 때
`dispute.accepted`	dispute에 이의가 제기되지 않은 상태로 수락될 때
`dispute.cancelled`	dispute가 철회되거나 취소될 때
`dispute.expired`	해결되지 않은 상태로 응답 기한이 지날 때
`dispute.won`	dispute가 판매자에게 유리하게 해결될 때
`dispute.lost`	dispute가 cardholder에게 유리하게 해결될 때

자세한 payload schema와 handler 예시는 Dispute Webhooks를 참조하세요.

Subscription Events

Event	발생 시점
`subscription.active`	subscription이 성공적으로 활성화되고 반복 청구가 예약될 때
`subscription.updated`	subscription field가 변경될 때(polling 없이 실시간 동기화)
`subscription.past_due`	renewal이 실패하고 grace period가 시작될 때. 기한까지 customer의 access는 유지됩니다.
`subscription.on_hold`	renewal 실패로 subscription이 일시적으로 보류될 때
`subscription.paused`	subscription이 일시 중지될 때
`subscription.unpaused`	일시 중지된 subscription이 재개될 때
`subscription.renewed`	다음 billing period에 대해 subscription이 성공적으로 갱신될 때
`subscription.plan_changed`	subscription이 upgrade, downgrade되거나 다른 add-on으로 변경될 때
`subscription.update_payment_method`	subscription의 payment method가 업데이트될 때
`subscription.cancelled`	merchant 또는 customer가 subscription을 취소할 때
`subscription.failed`	mandate 생성 중 subscription 생성이 실패할 때
`subscription.expired`	subscription이 term의 끝에 도달하여 만료될 때

자세한 payload schema와 handler 예시는 Subscription Webhooks를 참조하세요.

License Key Events

Event	발생 시점
`license_key.created`	product에 대한 새 license key가 생성될 때

전체 payload schema는 License Key Webhooks를 참조하세요.

Entitlement Grant Events

Event	발생 시점
`entitlement_grant.created`	customer에 대한 새 entitlement grant가 생성될 때. 자동으로 처리되는 license-key grant와 feature-flag grant는 `status: "Delivered"`와 함께 도착하며 별도의 `delivered` event는 발생하지 않습니다. 수동으로 처리되는 license key를 포함한 기타 grant는 `Pending`으로 도착합니다. Entitlement Grant를 참조하세요.
`entitlement_grant.delivered`	grant 처리가 완료될 때 — license key가 발급되거나, file link가 확인되거나, platform access가 부여됩니다.
`entitlement_grant.failed`	grant 처리가 실패할 때. payload에서 `error_code`와 `error_message`를 확인하세요.
`entitlement_grant.revoked`	access가 철회될 때. payload에서 `revocation_reason`를 확인하세요.

자세한 payload schema, sample event 및 전체 revocation_reason reference는 Entitlement Grant Webhooks를 참조하세요.

Credit Events

Event	발생 시점
`credit.added`	customer에게 credit이 부여될 때(subscription, one-time purchase, add-on 또는 API를 통해)
`credit.deducted`	usage 또는 manual debit을 통해 credit이 사용될 때
`credit.expired`	구성된 expiry period 후 사용하지 않은 credit이 만료될 때
`credit.rolled_over`	cycle 종료 시 사용하지 않은 credit이 새 grant로 이월될 때
`credit.rollover_forfeited`	max rollover count에 도달하여 credit이 소멸될 때
`credit.overage_charged`	잔액이 0을 초과하는 usage에 대해 overage charge가 적용될 때
`credit.overage_reset`	누적된 overage charge가 reset될 때(예: 새 billing cycle 시작 시)
`credit.manual_adjustment`	manual credit 또는 debit adjustment가 적용될 때
`credit.balance_low`	credit balance가 구성된 threshold 아래로 떨어질 때

자세한 payload schema와 handler 예시는 Credit-Based Billing Webhooks를 참조하세요.

Recovery Events

Event	발생 시점
`abandoned_checkout.detected`	60분 후 불완전하거나 실패한 checkout이 감지될 때
`abandoned_checkout.recovered`	customer가 recovery link를 통해 payment를 완료할 때

자세한 payload schema, field 설명 및 handler 예시는 Recovery Webhooks를 참조하세요.

Dunning Events

Event	발생 시점
`dunning.started`	past due 또는 on hold 상태가 되었거나 취소된 subscription에 대해 dunning 시도가 시작될 때
`dunning.recovered`	customer가 payment method를 업데이트하고 그 결과 발생한 charge가 성공할 때

자세한 payload schema, field 설명 및 handler 예시는 Recovery Webhooks를 참조하세요.

Payout Events

Payout event는 Dodo Payments에서 은행 계좌로 funds가 이동하는 과정을 추적합니다. 대시보드에 표시되는 payout statuses를 반영합니다. payload는 GET /payouts의 항목과 동일한 shape을 가진 payout object입니다.

Event	발생 시점
`payout.created`	automatic payout cycle 또는 off-cycle을 통해 payout이 생성될 때
`payout.in_progress`	payout due date가 도래하여 처리가 시작될 때
`payout.on_hold`	payout이 일시 중지되거나 review 상태가 될 때
`payout.success`	은행 계좌로의 payout이 settlement될 때
`payout.failed`	payout이 실패할 때. funds와 fee가 wallet으로 다시 credit됩니다.

Payout event는 terminal 상태가 아니며 엄격한 순서로 발생하지도 않습니다. 은행이 transfer를 반환하면 payout.failed가 payout.success 이후에 도착할 수 있고, 실패한 payout이 나중에 복구되면 payout.success가 payout.failed 이후에 도착할 수 있습니다. payload의 status는 항상 event type과 일치하므로, 각 event의 최상위 timestamp를 사용하여 최신 상태를 확인하세요.

payout.created는 이전에 payout.not_initiated로 발생했습니다. 기존 endpoint가 payout.not_initiated를 기준으로 filter하는 경우, 계속 일치하도록 filter를 payout.created로 업데이트하세요.

자세한 payload schema, field 설명 및 handler 예시는 Payout Webhooks를 참조하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Payment Events

Refund Events

Dispute Events

Subscription Events

License Key Events

Entitlement Grant Events

Credit Events

Recovery Events

Dunning Events

Payout Events

​Payment Events

​Refund Events

​Dispute Events

​Subscription Events

​License Key Events

​Entitlement Grant Events

​Credit Events

​Recovery Events

​Dunning Events

​Payout Events

Payment Events

Refund Events

Dispute Events

Subscription Events

License Key Events

Entitlement Grant Events

Credit Events

Recovery Events

Dunning Events

Payout Events