Skip to main content
Webhook Cover Image
웹훅은 Dodo Payments 계정에서 이벤트가 발생할 때 실시간 알림을 전달합니다. 이를 사용해 워크플로를 자동화하고, 데이터베이스를 업데이트하고, 알림을 보내고, 시스템을 동기화된 상태로 유지할 수 있습니다.
Dodo Payments 웹훅은 서명 검증 및 페이로드 구조에 Standard Webhooks 사양을 따릅니다.

주요 기능

웹훅은 기본 제공 보안, 자동 재시도 및 이벤트 필터링을 통해 실시간으로 전달됩니다. 모든 공식 SDK에는 서명 검증 헬퍼가 포함되어 있으며, 대시보드는 테스트, 모니터링 및 재생 도구를 제공합니다.

시작하기

1

Go to Developer → Webhooks

Dodo Payments Dashboard에서 Developer → Webhooks로 이동합니다.
2

Click Add Endpoint

Add endpoint를 클릭하여 새 웹훅 수신기를 만듭니다.
3

Enter Your Endpoint URL

Dodo Payments가 웹훅 이벤트를 전송할 HTTPS URL을 입력하거나 통합 커넥터(Slack, Discord, Zapier, Resend 등)를 선택하여 코드를 작성하지 않고 이벤트를 타사 서비스로 라우팅합니다.
4

Select Events

수신할 이벤트를 선택합니다. 이벤트는 리소스(결제, 구독, 분쟁 등)별로 구성됩니다. 개별 이벤트를 선택하거나 전체 리소스를 선택하여 관련된 모든 이벤트를 수신할 수 있습니다.
5

Save

Create endpoint를 클릭합니다. 엔드포인트의 Overview 탭에 웹훅 서명 시크릿이 표시됩니다.
웹훅 시크릿을 안전하게 보관하세요. 클라이언트 측 코드나 버전 관리 시스템에 절대 노출하지 마세요.
웹훅 시크릿을 교체하려면 엔드포인트를 열고 Overview 탭에서 시크릿 옆의 Rotate secret을 클릭합니다. 교체 후에도 기존 시크릿은 24시간 동안 유효합니다.

통합 커넥터

통합 커넥터를 사용하여 웹훅 이벤트를 타사 서비스로 직접 라우팅하면 맞춤 웹훅 핸들러를 구축하고 유지 관리할 필요가 없습니다.

커넥터 작동 방식

커넥터는 Dodo Payments 이벤트를 대상 서비스가 요구하는 형식으로 변환합니다. 제공해야 하는 세부 정보는 대상에 따라 다릅니다: 대시보드에는 비즈니스에서 사용할 수 있는 모든 커넥터가 표시됩니다. 각 대상이 이벤트로 수행할 수 있는 작업은 External Integrations을 참조하세요.

커넥터 설정

엔드포인트를 생성하거나 편집할 때 커넥터를 선택하면 사이드 시트에 해당 대상의 설정 지침이 표시됩니다. 저장하기 전에 변환을 테스트하여 이벤트가 올바르게 변환되는지 확인하세요.
코드를 작성하지 않고 지원되는 대상에 연결하려면 커넥터를 사용하세요. 맞춤 로직이 필요하면 대신 변환이 적용된 표준 엔드포인트를 사용하세요.

구독 이벤트 구성

각 웹훅 엔드포인트가 수신할 이벤트를 구성합니다.
1

Navigate to Webhook Endpoints

Developer → Webhooks로 이동하여 엔드포인트를 클릭합니다.
2

Open Event Configuration

Edit를 클릭하여 엔드포인트 구성 사이드 시트를 엽니다.
3

Select Events

이벤트 유형 선택기에는 검색 가능한 트리로 구성된 모든 웹훅 이벤트가 리소스별로 그룹화되어 표시됩니다(예: payment, subscription, dispute). 수신하려는 이벤트 옆의 확인란을 선택합니다. 개별 이벤트, 전체 리소스를 선택하거나 여러 항목을 조합할 수 있습니다.
4

Save Configuration

Save를 클릭하여 변경 사항을 적용합니다.
모든 이벤트의 선택을 해제하면 웹훅 엔드포인트가 모든 이벤트 유형을 수신합니다. 애플리케이션에 필요한 이벤트만 선택하세요.

이벤트 카탈로그

Developer → Webhooks로 이동하고 Event catalog 탭을 열어 Dodo Payments가 전송할 수 있는 모든 이벤트 유형을 확인합니다. 이벤트를 선택하면 해당 스키마와 샘플 페이로드를 볼 수 있습니다.

Webhook Events Guide

리소스별로 그룹화된 이벤트를 참조 문서로 찾아볼 수 있습니다.

웹훅 전달

시간 초과

webhook의 연결 및 읽기 작업에는 모두 30초 timeout이 적용됩니다. 200 status code를 즉시 반환하여 webhook을 비동기적으로 처리한 다음, 백그라운드에서 이벤트를 처리하세요.

자동 재시도

전송에 실패한 경우 exponential backoff 방식으로 재시도하며, 총 최대 8회까지 시도합니다: 대시보드를 사용하여 실패한 메시지를 수동으로 다시 전송하거나 특정 시간 범위의 메시지를 일괄 복구할 수 있습니다.

멱등성

각 webhook에는 고유한 webhook-id header가 포함됩니다. 재시도로 인해 동일한 이벤트가 여러 번 전달될 수 있으므로 이 ID를 저장하여 중복 이벤트를 감지하고 건너뛰세요.
항상 멱등성 검사를 구현하세요. 재시도로 인해 동일한 이벤트를 여러 번 수신할 수 있습니다.

이벤트 순서

재시도 또는 네트워크 상태로 인해 이벤트가 순서에 맞지 않게 도착할 수 있습니다. 각 webhook에는 timestamp field가 포함되므로, 애플리케이션에서 필요한 경우 이를 사용하여 이벤트 순서를 정렬하세요. 전달 시점의 최신 payload 상태는 항상 수신합니다.

Webhook 보안

항상 webhook payload를 검증하고 HTTPS를 사용하세요.

Signature 확인

각 webhook에는 webhook-signature header가 포함됩니다. 이는 secret key로 서명된 payload 및 timestamp의 HMAC SHA256 signature입니다.

SDK 검증(권장)

모든 공식 SDK에는 기본 제공 helper가 포함되어 있습니다. client를 초기화할 때 DODO_PAYMENTS_WEBHOOK_KEY를 설정한 다음 unwrap()를 호출하여 payload를 검증하고 parsing하세요. 두 가지 method를 사용할 수 있습니다:
  • unwrap — webhook secret key로 signature를 검증한 다음 payload를 parsing합니다.
  • unsafe_unwrap — 검증 없이 payload를 parsing합니다. 테스트 용도로만 사용하세요.
method 이름은 각 언어의 규칙을 따릅니다. TypeScript에서는 unwrap / unsafeUnwrap, Python에서는 unwrap / unsafe_unwrap, Go에서는 Unwrap / UnsafeUnwrap입니다.
Dodo Payments client를 초기화할 때 DODO_PAYMENTS_WEBHOOK_KEY를 통해 webhook secret을 제공하세요.

수동 검증(대안)

SDK를 사용하지 않는 경우 직접 signature를 검증하세요:
  1. webhook-id, webhook-timestamp 및 raw request body를 마침표로 연결하여 signed content를 구성합니다: {id}.{timestamp}.{body}. JSON parsing 전에 수신한 raw body를 그대로 사용하세요.
  2. webhook secret을 가져옵니다. whsec_로 시작하는 경우 해당 prefix를 제거한 다음 나머지를 base64-decode하여 signing key를 얻습니다.
  3. signing key로 signed content의 HMAC-SHA256을 계산하고 결과를 base64-encode합니다.
  4. webhook-signature header에는 하나 이상의 공백으로 구분된 signature가 있으며, 각 signature 형식은 v1,<base64-signature>입니다. v1 signature 중 하나라도 본인의 signature와 일치하면 request가 유효합니다. constant-time function으로 비교하세요.
  5. replay attack을 방지하려면 webhook-timestamp가 현재 시간과 지나치게 차이가 날 경우 request를 거부하세요. Standard Webhooks libraries는 5분을 허용합니다.
참조 구현은 Standard Webhooks libraries를 확인하세요. 이벤트 payload 형식은 Webhook Payload를 참조하세요.

Source IP 주소

지원되는 authentication method는 signature verification입니다. 이는 request가 webhook secret으로 서명되었음을 증명하지만, network-level check로는 이를 확인할 수 없습니다. Webhook delivery는 시간이 지나면서 변경되는 IP address pool에서 전송됩니다. authentication에 IP allowlist를 사용하지 마세요. 대신 Verifying Signatures에 설명된 대로 항상 webhook-signature header를 검증하세요. firewall에 allowlist가 필요한 경우:
  • 주소를 영구적으로 hardcode하지 마세요. 범위는 시간이 지나면서 변경되며, 오래된 규칙은 delivery를 조용히 차단합니다.
  • firewall을 제한하기 전에 support@dodopayments.com에 현재 범위를 요청하세요.
  • 변경 알림을 확인하세요. delivery address가 변경되면 영향을 받는 merchant에게 email로 알립니다. 지정된 날짜 전에 업데이트를 적용하세요.
  • 추가한 network rule과 관계없이 signature verification을 활성화된 상태로 유지하세요.
serverless 및 managed hosting platform에서는 inbound IP filtering을 사용할 수 없거나 실용적이지 않은 경우가 많습니다. 이러한 환경에서는 signature verification이 올바른 제어 방법입니다.
차단된 delivery는 failure로 처리되며 Automatic Retries에 설명된 일정에 따라 재시도됩니다. firewall rule로 인해 delivery가 실패한 경우 rule을 수정한 후 다시 전송할 수 있습니다. Replaying and Recovering Messages를 참조하세요.

Webhook에 응답

webhook handler는 수신을 확인하기 위해 2xx status code를 반환해야 합니다. 다른 response는 모두 failure로 처리되며 webhook이 재시도됩니다.

모범 사례

  • HTTPS만 사용하세요. HTTP endpoint는 interception에 취약합니다.
  • 즉시 응답하세요. 200 status code를 즉시 반환한 다음 이벤트를 비동기적으로 처리하세요.
  • 멱등성을 구현하세요. webhook-id header를 사용하여 중복 이벤트를 감지하고 건너뛰세요.
  • secret을 안전하게 보호하세요. DODO_PAYMENTS_WEBHOOK_KEY를 environment variable 또는 secrets manager에 저장하고, version control에는 절대 저장하지 마세요.

Webhook Payload 구조

Request 형식

Headers

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

Request Body

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

Payload 예시

Event Types

사용 가능한 모든 webhook event type 찾아보기

Event Payloads

각 event의 상세 payload schema 확인하기

Handle Payment Failures

payment.failed에 대응하고 declined payment 복구하기

Webhook 테스트

예시 이벤트 전송

대시보드에서 직접 webhook integration을 테스트하세요:
1

Navigate to Webhooks

Developer → Webhooks로 이동하여 endpoint를 클릭합니다.
2

Open Testing Tab

Testing tab을 클릭합니다.
3

Send Example

event type을 선택하고 Send example을 클릭합니다. sample payload는 실제 event와 동일하게, 같은 방식으로 서명되어 endpoint URL로 전달됩니다.
4

Check Your Endpoint

event가 도착했는지, signature verification이 통과했는지, 2xx status code를 반환했는지 확인합니다.
Testing tab에서 전송된 실패 메시지는 다른 webhook과 마찬가지로 일반 retry schedule에 따라 재시도됩니다.

구현 예시

webhook verification 및 handling을 포함한 완전한 Express.js 구현입니다:
production event를 처리하기 전에 대시보드 testing interface를 사용하여 webhook handler를 충분히 테스트하세요. 이를 통해 문제를 조기에 식별하고 수정할 수 있습니다.

CLI로 Webhook 테스트

Dodo Payments CLI에는 local development 중 webhook을 테스트하기 위한 두 가지 command가 있습니다.

로컬에서 Live Webhook 수신

test mode account의 실제 webhook event를 local development server로 전달합니다:
CLI는 WebSocket connection을 열고 모든 webhook event를 local endpoint(예: http://localhost:3000/webhook)로 전달하며, signature verification 테스트를 위해 모든 header를 유지합니다.
listener는 test mode API key에서만 작동합니다. dodo login를 실행하고 먼저 Test Mode를 선택하세요.

Mock Webhook Event 트리거

실제 transaction을 생성하지 않고 모든 endpoint로 mock webhook payload를 전송합니다:
이 interactive tool을 사용하면 event type을 선택하고 실제와 유사한 mock payload를 endpoint로 전송할 수 있습니다. 한 session에서 여러 event를 테스트할 수 있도록 반복 실행됩니다. trigger command는 subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning 및 entitlement grant family를 지원합니다. subscription.past_due 또는 subscription.unpaused는 전송하지 않습니다. 정확한 목록은 Supported Webhook Events를 참조하세요.
dodo wh trigger의 mock webhook payload에는 signature가 없습니다. 테스트 중 webhook handler에서는 검증되지 않은 parse method(TypeScript의 unsafeUnwrap, Python의 unsafe_unwrap, Go의 UnsafeUnwrap)를 사용하세요.

CLI Webhook Testing Docs

전체 CLI webhook testing documentation 보기

고급 설정

Advanced tab에서는 webhook endpoint 동작을 세밀하게 조정하기 위한 추가 configuration option을 제공합니다.

Rate Limiting(Throttling)

webhook event가 endpoint로 전달되는 rate를 제어합니다. 기본적으로 webhook에는 rate limit이 적용되지 않으며 event가 발생하는 즉시 전달됩니다.
1

Open Advanced Tab

endpoint details page에서 Advanced tab을 클릭합니다.
2

Configure Rate Limit

Endpoint throttling section을 펼칩니다.
3

Set Your Limit

초당 최대 메시지 수를 입력하고 Save를 클릭합니다. 이 rate를 초과한 delivery는 삭제되지 않고 queue에 추가됩니다.

Custom Headers

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

Add Headers

Custom headers section에서 header name과 value를 입력합니다.
2

Add Multiple Headers

추가 header마다 Add header를 클릭한 다음 Save를 클릭합니다.

Transformations

Transformation을 사용하면 webhook payload를 수정하고 필요한 경우 다른 URL로 redirect할 수 있습니다. 다음과 같은 경우 transformation을 사용하세요:
  • 처리 전에 payload structure 수정
  • content에 따라 webhook을 다른 endpoint로 routing
  • payload에서 field 추가 또는 제거
  • data format 변환
1

Enable Transformations

Transformation section에서 Enable transformation을 켭니다.
2

Configure Transformation

code editor에서 transformation rule을 JavaScript로 작성한 다음 Save를 클릭합니다. code는 handler()의 webhook object를 반환해야 합니다.
3

Test Transformation

production 환경으로 전환하기 전에 transformation test interface를 사용하여 transformation이 올바르게 작동하는지 확인합니다.
Transformation은 webhook delivery performance에 영향을 줄 수 있습니다. 충분히 테스트하고 transformation logic을 간단하고 효율적으로 유지하세요.

Webhook Log 모니터링

Logs tab에서 webhook delivery status를 확인할 수 있습니다.
1

Navigate to Logs Tab

Developer → Webhooks로 이동하여 Logs tab을 엽니다.
2

Browse Delivery History

Event type, Message ID, Event ID, Sent at, Attempted at, Response code 및 Duration column이 있는 모든 webhook delivery attempt table을 확인합니다.
3

Search and Filter

search bar를 사용하여 ID 또는 event type으로 특정 message를 찾습니다. status(Succeeded, Failed, Pending 등)로 filter하여 조사할 event에 집중하세요.
4

View Message Details

message를 클릭하여 message detail page를 엽니다. 다음 정보를 확인할 수 있습니다:
  • 전체 webhook payload
  • response code 및 duration을 포함한 모든 delivery attempt
  • 각 attempt의 timestamp
  • endpoint의 error message
각 attempt에는 page를 벗어나지 않고 해당 message 하나를 다시 전송할 수 있는 Replay action이 있습니다.

Activity 모니터링

Developer → Webhooks로 이동하여 Activity tab을 열면 endpoint 전반의 delivery performance를 확인할 수 있습니다. Delivery activity는 시간에 따른 attempt를 표시하며, window에 따라 Attempts per 5 minutes, Attempts per hour 또는 Attempts per day 단위로 그룹화됩니다. 각 bar는 outcome별로 나뉘며 segment 위에 마우스를 올리면 status, attempt 수 및 전체에서 차지하는 비율이 표시됩니다. endpoint의 Overview tab에 있는 **Delivery stats (last 24h)**에서는 지난 하루 동안의 동일한 정보를 요약합니다.
Endpoints tab의 Error rate (24h) column을 통해 즉시 주의가 필요한 endpoint를 확인할 수 있습니다.

메시지 다시 전송 및 복구

메시지를 다시 전송하는 방법은 필요한 메시지 수에 따라 다릅니다:
  • 메시지 하나 — Logs tab에서 열고 attempt의 Replay action을 사용합니다.
  • 메시지 범위 — bulk mode는 한 번에 하나의 endpoint에만 적용되므로 endpoint를 엽니다.

일괄 다시 전송

Developer → Webhooks에서 endpoint를 엽니다. 세 가지 mode를 사용할 수 있으며, 각 mode는 해당 endpoint에만 적용됩니다:
1

Open More Actions

endpoint에서 More actions를 열고 위의 세 가지 mode 중 하나를 선택합니다.
2

Set the Range

table에 나열된 대로 선택한 mode에서 요청하는 범위를 입력합니다.
3

Start the Run

선택한 mode에 따라 Recover 또는 Replay를 클릭합니다.
각 실행은 endpoint의 Overview tab에 있는 Replay history에 표시되며, mode, time range, status 및 다시 전송된 message 수가 포함됩니다.

Email 알림

webhooks dashboard는 delivery failure에 대한 email alert를 제공하지 않습니다. delivery를 모니터링하려면 Developer → Webhooks로 이동하여 Logs 및 Activity tab을 확인하세요.

Cloud Platform에 배포

주요 cloud provider에 webhook handler를 배포하기 위한 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 배포

관련 API Reference

Create Webhook

webhook endpoint를 programmatically 생성 및 configuration

List Webhooks

webhook endpoint 조회 및 관리
마지막 수정일 2026년 9월 26일