Skip to main content
Webhook Cover Image
Webhooks는 Dodo Payments 계정에서 특정 이벤트가 발생할 때 실시간 알림을 제공합니다. Webhooks를 사용하여 워크플로를 자동화하고, 데이터베이스를 업데이트하고, 알림을 전송하며, 시스템을 동기화된 상태로 유지할 수 있습니다.
당사의 webhook 구현은 Standard Webhooks 사양을 따르므로 업계 모범 사례 및 기존 webhook 라이브러리와의 호환성을 보장합니다.

주요 기능

Real-time Delivery

이벤트가 발생하면 즉시 알림 수신

Secure by Default

HMAC SHA256 서명 검증 포함

Automatic Retries

지수 백오프를 적용한 기본 재시도 로직

Event Filtering

필요한 이벤트만 구독

시작하기

1

Access Webhook Settings

DodoPayments Dashboard로 이동한 다음 Developer > Webhooks로 이동합니다.
2

Create Webhook Endpoint

새 webhook endpoint를 생성하려면 Add Webhook를 클릭합니다.
Add Webhook
3

Add Endpoint URL

webhook 이벤트를 수신할 URL을 입력합니다.
4

Select Events to Receive

이벤트 목록에서 webhook endpoint가 수신할 특정 이벤트를 선택합니다.
선택한 이벤트만 endpoint로 webhook을 트리거하므로 불필요한 트래픽과 처리를 줄일 수 있습니다.
5

Get Secret Key

설정 페이지에서 webhook Secret Key를 가져옵니다. 수신한 webhook의 진위를 확인할 때 사용합니다.
webhook secret key를 안전하게 보관하고 client-side code나 public repository에 절대 노출하지 마세요.
6

Rotate Secret (Optional)

필요한 경우 보안을 강화하기 위해 webhook secret을 교체할 수 있습니다. webhook 설정에서 Rotate Secret 버튼을 클릭합니다.
secret을 교체하면 기존 secret이 만료되고 새 secret으로 대체됩니다. 이전 secret은 이후 24시간 동안만 유효합니다. 그 후 이전 secret으로 검증을 시도하면 실패합니다.
secret이 유출되었다고 의심되는 경우 또는 정기적으로 secret rotation을 사용하세요.

구독 이벤트 구성

각 webhook endpoint에서 수신할 특정 이벤트를 구성할 수 있습니다.

이벤트 구성에 액세스

1

Navigate to Webhook Details

Dodo Payments Dashboard로 이동한 다음 Developer > Webhooks로 이동합니다.
2

Select Your Endpoint

구성하려는 webhook endpoint를 클릭합니다.
3

Open Event Settings

webhook details 페이지에서 “Subscribed events” 섹션을 찾습니다. 이벤트 구독을 수정하려면 Edit 버튼을 클릭합니다.

이벤트 구독 관리

1

View Available Events

인터페이스에는 사용 가능한 모든 webhook 이벤트가 계층 구조로 표시됩니다. 이벤트는 카테고리별로 그룹화됩니다(예: dispute, payment, subscription).
2

Search and Filter

검색창에 이벤트 이름이나 키워드를 입력하여 특정 이벤트를 빠르게 찾습니다.
3

Select Events

수신하려는 이벤트 옆의 확인란을 선택합니다. 다음 작업을 수행할 수 있습니다.
  • 개별 하위 이벤트 선택(예: dispute.accepted, dispute.challenged)
  • 상위 이벤트를 선택하여 관련된 모든 하위 이벤트 수신
  • 필요에 따라 특정 이벤트 조합
4

Review Event Details

각 이벤트 옆의 정보 아이콘(ⓘ) 위에 마우스를 올리면 해당 이벤트가 트리거되는 시점에 대한 설명을 볼 수 있습니다.
5

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를 검증할 수 있습니다.
  1. webhook-id, webhook-timestamp 및 정확한 원시 문자열화 payload를 마침표(.)로 연결하여 서명된 메시지를 구성합니다.
  2. Dashboard의 webhook secret key를 사용하여 해당 문자열의 HMAC SHA256을 계산합니다.
  3. 계산된 signature를 webhook-signature header와 비교합니다. 일치하면 webhook은 진본입니다.
Standard Webhooks 사양을 따릅니다. signature를 검증하려면 해당 라이브러리를 사용할 수 있습니다: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. 이벤트 payload 형식은 Webhook Payload를 참조하세요.

Webhook 응답

  • webhook handler는 이벤트 수신을 확인하기 위해 2xx status code를 반환해야 합니다.
  • 그 외의 모든 response는 실패로 처리되며 webhook이 재시도됩니다.

모범 사례

webhook endpoint에는 항상 HTTPS URL을 사용하세요. HTTP endpoint는 man-in-the-middle attack에 취약하며 webhook data를 노출합니다.
webhook을 수신하는 즉시 200 status code를 반환하세요. 시간 초과를 방지하려면 이벤트를 비동기적으로 처리합니다.
webhook-id header를 사용하여 멱등성을 구현하고 동일한 이벤트를 부작용 없이 여러 번 안전하게 처리하세요.
환경 변수 또는 secrets manager를 사용하여 webhook secret을 안전하게 저장하세요. secret을 version control에 절대 commit하지 마세요.

Webhook Payload 구조

Webhook payload 구조를 이해하면 이벤트를 올바르게 파싱하고 처리할 수 있습니다.

Request 형식

Headers

string
필수
이 webhook 이벤트의 고유 식별자입니다. 멱등성 검사에 사용하세요.
string
필수
webhook의 진위를 확인하기 위한 HMAC SHA256 signature입니다.
string
필수
webhook이 전송된 시점의 Unix timestamp(초 단위)입니다.

Request Body

string
필수
Dodo Payments business identifier입니다.
string
필수
이 webhook을 트리거한 이벤트 유형입니다(예: payment.succeeded, subscription.active).
string
필수
이벤트가 발생한 시점의 ISO 8601 형식 timestamp입니다.
object
필수
이벤트에 대한 상세 정보를 포함하는 이벤트별 payload입니다.

Payload 예시

Event Types

사용 가능한 모든 webhook 이벤트 유형 탐색

Event Payloads

각 이벤트의 상세 payload schema 확인

Handle Payment Failures

payment.failed에 대응하고 거부된 payment 복구

Webhooks 테스트

실제 운영을 시작하기 전에 Dodo Payments dashboard에서 webhook integration을 직접 테스트하여 endpoint가 올바르게 작동하는지 확인할 수 있습니다.
Endpoint Details

테스트 인터페이스에 액세스

1

Navigate to Webhooks

Dodo Payments Dashboard로 이동한 다음 Developer > Webhooks로 이동합니다.
2

Select Your Endpoint

webhook endpoint를 클릭하여 details 페이지로 이동합니다.
3

Open Testing Tab

webhook testing interface에 액세스하려면 Testing 탭을 클릭합니다.

Webhook 테스트

테스트 인터페이스는 webhook endpoint를 테스트할 수 있는 종합적인 방법을 제공합니다.
1

Select Event Type

dropdown menu에서 테스트할 특정 이벤트 유형을 선택합니다(예: payment.succeeded, payment.failed 등).
dropdown에는 endpoint가 수신할 수 있는 모든 webhook 이벤트 유형이 포함됩니다.
2

Review Schema and Example

인터페이스에는 선택한 이벤트 유형의 Schema(data structure)와 Example(sample payload)이 모두 표시됩니다.
3

Send Test Event

Send Example 버튼을 클릭하여 endpoint로 test webhook을 전송합니다.
중요: testing interface를 통해 전송된 실패한 message는 재시도되지 않습니다. 이 기능은 테스트 전용입니다.

테스트 확인

1

Check Your Endpoint

test event가 수신되었는지 확인하려면 webhook endpoint log를 모니터링합니다.
2

Verify Signature

test payload에서 signature verification이 올바르게 작동하는지 확인합니다.
3

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로 전달되는 속도를 제어합니다.
1

Access Rate Limit Settings

Advanced 탭에서 “Rate Limit (throttling)” 섹션을 찾습니다.
2

Configure Rate Limit

rate limit 설정을 수정하려면 Edit 버튼을 클릭합니다.
기본적으로 webhook에는 “No rate limit”이 적용되므로 이벤트가 발생하는 즉시 전달됩니다.
3

Set Limits

webhook delivery frequency를 제어하고 system overload를 방지하도록 원하는 rate limit을 구성합니다.
webhook handler가 이벤트를 처리할 시간이 필요하거나 여러 이벤트를 함께 batch 처리하려는 경우 rate limiting을 사용하세요.

Custom Headers

endpoint로 전송되는 모든 webhook request에 custom HTTP header를 추가합니다. authentication, routing 또는 webhook request에 metadata를 추가할 때 유용합니다.
1

Add Custom Header

“Custom Headers” 섹션에서 custom header의 KeyValue를 입력합니다.
2

Add Multiple Headers

필요한 만큼 custom header를 추가하려면 + 버튼을 클릭합니다.
3

Save Configuration

custom header는 이 endpoint로 전송되는 모든 webhook request에 포함됩니다.

Transformations

Transformations를 사용하면 webhook payload를 수정하고 다른 URL로 redirect할 수 있습니다. 이 강력한 기능으로 다음 작업을 수행할 수 있습니다.
  • 처리하기 전에 payload 구조 수정
  • content에 따라 webhook을 다른 endpoint로 route
  • payload에서 field 추가 또는 제거
  • data 형식 변환
1

Enable Transformations

transformation 기능을 활성화하려면 Enabled switch를 켭니다.
2

Configure Transformation

transformation rule을 정의하려면 Edit transformation을 클릭합니다.
JavaScript를 사용하여 webhook payload를 변환하고 다른 target URL을 지정할 수 있습니다.
3

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 및 관리할 수 있습니다.
Logs

Activity 모니터링

Activity 탭은 visual analytics를 통해 webhook delivery performance에 대한 실시간 insight를 제공합니다.
Activity

Email Alerts

자동 email notification으로 webhook 상태를 확인하세요. webhook delivery가 실패하기 시작하거나 endpoint가 응답하지 않으면 email alert를 받아 문제를 신속하게 해결하고 integration을 원활하게 유지할 수 있습니다.
Webhook Alerting Settings showing email notifications configuration

Email Alerts 활성화

1

Navigate to Alerting Settings

Dodo Payments Dashboard로 이동한 다음 Dashboard → Webhooks → Alerting으로 이동합니다.
2

Enable Email Notifications

webhook delivery issue에 대한 alert를 받으려면 Email notifications를 켭니다.
3

Configure Email Address

webhook alert를 받을 email address를 입력합니다. webhook setup에서 integration에 영향을 줄 수 있는 delivery issue와 같은 특정 이벤트가 발생하면 이 address로 notification을 전송합니다.
webhook delivery problem을 조기에 파악하고 안정적인 integration을 유지하려면 email alert를 활성화하세요. delivery가 실패하거나 endpoint가 응답하지 않게 되면 notification을 받습니다.

Cloud Platform에 배포

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
마지막 수정일 2026년 7월 31일