Skip to main content
Webhook Cover Image
Dodo Paymentsアカウントでイベントが発生すると、webhookによってリアルタイム通知が配信されます。これらを使用して、ワークフローの自動化、データベースの更新、通知の送信、システム間の同期を行えます。
Dodo Paymentsのwebhookは、署名検証とペイロード構造に関してStandard Webhooks仕様に準拠しています。

主な機能

webhookは、組み込みのセキュリティ、自動再試行、イベントフィルタリングを備えたリアルタイム配信を提供します。すべての公式SDKには署名検証ヘルパーが含まれており、ダッシュボードではテスト、監視、再送のためのツールを利用できます。

はじめに

1

Go to Developer → Webhooks

Dodo Payments Dashboardで、Developer → Webhooksに移動します。
2

Click Add Endpoint

Add endpointをクリックして、新しいwebhook受信先を作成します。
3

Enter Your Endpoint URL

Dodo Paymentsがwebhookイベントを送信するHTTPS URLを入力するか、統合コネクタ(Slack、Discord、Zapier、Resendなど)を選択して、コードを書かずにイベントをサードパーティサービスへルーティングします。
4

Select Events

受信するイベントを選択します。イベントはリソース(payment、subscription、disputeなど)ごとに整理されています。個別のイベントまたはリソース全体を選択して、関連するすべてのイベントを受信できます。
5

Save

Create endpointをクリックします。webhook signing secretがエンドポイントのOverviewタブに表示されます。
webhook secretは安全に保管してください。クライアント側のコードやバージョン管理システムに決して公開しないでください。
webhook secretをローテーションするには、エンドポイントを開き、Overviewタブのsecretの横にあるRotate secretをクリックします。ローテーション後も、古いsecretは24時間有効です。

Integration Connectors

統合コネクタを使用してwebhookイベントをサードパーティサービスへ直接ルーティングし、カスタムwebhookハンドラーを構築・保守する必要をなくします。

コネクタの仕組み

コネクタは、Dodo Paymentsのイベントを送信先が想定する形式に変換します。入力する詳細情報は送信先によって異なります。 ダッシュボードには、ビジネスで利用可能なすべてのコネクタが表示されます。各送信先でイベントをどのように利用できるかについては、External Integrationsを参照してください。

コネクタの設定

エンドポイントの作成または編集時にコネクタを選択すると、サイドシートに送信先の設定手順が表示されます。保存する前に変換をテストして、イベントが正しく変換されることを確認してください。
コードを書かずに、コネクタを使用してサポートされている送信先へ到達できます。カスタムロジックが必要な場合は、代わりにtransformationを使用した標準エンドポイントを利用してください。

購読イベントの設定

各webhookエンドポイントが受信するイベントを設定します。
1

Navigate to Webhook Endpoints

Developer → Webhooksに移動し、エンドポイントをクリックします。
2

Open Event Configuration

Editをクリックして、エンドポイント設定のサイドシートを開きます。
3

Select Events

イベントタイプセレクターには、リソース(例:payment、subscription、dispute)ごとにグループ化された、検索可能なツリー形式のすべてのwebhookイベントが表示されます。受信するイベントの横にあるチェックボックスをオンにします。個別のイベント、リソース全体、またはそれらを組み合わせて選択できます。
4

Save Configuration

Saveをクリックして変更を適用します。
すべてのイベントの選択を解除すると、webhookエンドポイントはすべてのイベントタイプを受信します。アプリケーションに必要なイベントだけを選択してください。

イベントカタログ

Developer → Webhooksに移動し、Event catalogタブを開くと、Dodo Paymentsが送信できるすべてのイベントタイプを確認できます。イベントを選択すると、そのスキーマとサンプルペイロードが表示されます。

Webhook Events Guide

リファレンスドキュメントとして、リソースごとにグループ化されたイベントを参照できます。

Webhook配信

タイムアウト

Webhook の接続および読み取り操作には、30 秒のタイムアウトが設定されています。200 status code を直ちに返して、Webhook を非同期で処理し、その後バックグラウンドでイベントを処理してください。

自動再試行

配信に失敗すると、指数バックオフを使用して、合計最大 8 回まで再試行されます。 ダッシュボードを使用して、失敗したメッセージを手動で再送するか、特定の期間のメッセージを一括で復旧してください。

冪等性

各 Webhook には一意の webhook-id header が含まれます。この ID を保存して重複イベントを検出し、スキップしてください。再試行によって同じイベントが複数回配信される場合があります。
必ず冪等性チェックを実装してください。再試行により、同じイベントを複数回受信する可能性があります。

イベントの順序

再試行やネットワークの状態により、イベントが順不同で届く場合があります。各 Webhook には timestamp field が含まれます。アプリケーションで順序付けが必要な場合は、この field を使用してください。配信時点での最新の payload state を常に受け取ります。

Webhook のセキュリティ保護

必ず Webhook payload を検証し、HTTPS を使用してください。

Signature の検証

各 Webhook には webhook-signature header が含まれます。これは payload と timestamp の HMAC SHA256 signature で、secret key によって署名されています。

SDK による検証(推奨)

すべての公式 SDK には組み込みの helper が含まれています。client の初期化時に DODO_PAYMENTS_WEBHOOK_KEY を設定し、unwrap() を呼び出して payload を検証・解析してください。使用できる method は 2 つあります。
  • unwrap — webhook secret key で signature を検証してから、payload を解析します。
  • unsafe_unwrap — 検証せずに payload を解析します。テスト専用です。
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 をピリオドで結合して、署名対象の content を作成します。{id}.{timestamp}.{body}。JSON parsing 前の、受信したままの raw body を使用してください。
  2. webhook secret を取得します。whsec_ で始まる場合は、その prefix を削除し、残りを base64-decode して signing key を取得します。
  3. signing key を使用して署名対象 content の HMAC-SHA256 を計算し、結果を base64-encode します。
  4. webhook-signature header には、v1,<base64-signature> 形式の、スペース区切りの signature が 1 つ以上含まれます。いずれかの v1 signature が自分の signature と一致すれば、request は有効です。constant-time function と比較してください。
  5. replay attack を防ぐため、webhook-timestamp が現在時刻から大きく離れている場合は request を拒否します。Standard Webhooks libraries では 5 分が許容されています。
実装例については、Standard Webhooks libraries を参照してください。event payload の形式については、Webhook Payload を参照してください。

Source IP アドレス

サポートされている authentication method は signature verification です。これは、network-level check では証明できない、request が webhook secret で署名されたことを証明します。 Webhook 配信元は、時間の経過とともに変化する IP address pool です。authentication に IP allowlist を使用しないでください。代わりに、Verifying Signatures の説明に従い、常に webhook-signature header を検証してください。 firewall で allowlist が必要な場合:
  • アドレスを恒久的に hardcode しないでください。 Range は時間とともに変化するため、古い rule によって配信が気付かないうちにブロックされます。
  • firewall を制限する前に、support@dodopayments.com から現在の range をリクエストしてください。
  • 変更通知を確認してください。 配信アドレスが変更されると、影響を受ける merchant に email で通知します。指定された日付までに更新を適用してください。
  • 追加した network rule にかかわらず、signature verification を有効にしたままにしてください。
Serverless および managed hosting platform では、inbound IP filtering を利用できないか、実用的でないことがよくあります。このような環境では、signature verification が適切な control です。
ブロックされた配信は failure として扱われ、Automatic Retries に記載されたスケジュールで再試行されます。firewall rule によって配信が失敗した場合は、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 の一意識別子です。冪等性チェックに使用します。
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
必須
event が発生した時刻の ISO 8601 formatted timestamp です。
object
必須
event に関する詳細情報を含む、event 固有の payload です。

Payload の例

Event Types

利用可能なすべての webhook event type を表示

Event Payloads

各 event の詳細な payload schema を表示

Handle Payment Failures

payment.failed に対応し、declined payment を復旧

Webhook のテスト

Example Event の送信

ダッシュボードから直接 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 から送信された failed message は、他の Webhook と同じ通常の retry schedule で再試行されます。

実装例

Webhook verification と handling を含む完全な Express.js implementation:
production event を処理する前に、dashboard testing interface を使用して webhook handler を十分にテストしてください。これにより、問題を早期に特定して修正できます。

CLI を使用した Webhook のテスト

Dodo Payments CLI には、local development 中に Webhook をテストするための command が 2 つあります。

Live Webhook をローカルでリッスンする

test mode account から local development server に実際の Webhook event を転送します。
CLI は WebSocket connection を開き、すべての Webhook event を local endpoint(例:http://localhost:3000/webhook)に転送します。signature verification testing に必要なすべての 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 に送信できます。loop するため、1 回の 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 には署名がありません。テスト中の webhook handler では、unverified parse method(TypeScript の unsafeUnwrap、Python の unsafe_unwrap、Go の UnsafeUnwrap)のみを使用してください。

CLI Webhook Testing Docs

CLI Webhook testing documentation の全文を表示

詳細設定

Advanced tab では、Webhook endpoint の動作を細かく調整するための追加 configuration options を利用できます。

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

1 秒あたりの最大 message 数を入力し、Save をクリックします。この rate を超える配信は破棄されず、queue に入れられます。

Custom Headers

endpoint に送信されるすべての Webhook request に custom HTTP headers を追加します。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 に route する
  • payload から field を追加または削除する
  • data format を変換する
1

Enable Transformations

Transformation section で Enable transformation をオンにします。
2

Configure Transformation

code editor で JavaScript による transformation rule を記述し、Save をクリックします。code は handler() の webhook object を返す必要があります。
3

Test Transformation

transformation test interface を使用して、本番稼働前に transformation が正しく動作することを確認します。
Transformation は Webhook delivery performance に影響する可能性があります。十分にテストし、transformation logic はシンプルかつ効率的にしてください。

Webhook Logs の監視

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 の columns を含む、すべての 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 には Replay action があり、page を離れずにその message だけを再配信できます。

Activity の監視

Developer → Webhooks に移動し、Activity tab を開くと、endpoint 全体の delivery performance を確認できます。 Delivery activity には、期間に応じて Attempts per 5 minutes、Attempts per hour、または Attempts per day 単位で集計された attempt の推移が表示されます。各 bar は outcome 別に分割され、segment に hover すると status、attempt 数、全体に占める割合が表示されます。endpoint の Overview tab にある Delivery stats (last 24h) には、過去 1 日分の同じ情報がまとめられます。
Endpoints tab の Error rate (24h) column では、対応が必要な endpoint をすぐに確認できます。

Message の再送と復旧

message の再配信方法は、必要な件数によって異なります。
  • 1 件の message — Logs tab から開き、attempt の Replay action を使用します。
  • 複数の message の range — bulk mode は一度に 1 つの endpoint に対して動作するため、endpoint を開きます。

一括再送

Developer → Webhooks から endpoint を開きます。3 つの mode が利用でき、それぞれその endpoint のみに作用します。
1

Open More Actions

endpoint で More actions を開き、上記 3 つの mode のいずれかを選択します。
2

Set the Range

table に記載されている、その mode が要求する range を入力します。
3

Start the Run

選択した mode に応じて Recover または Replay をクリックします。
各 run は endpoint の Overview tab にある Replay history に表示されます。mode、time range、status、再送された message 数を確認できます。

Email Alerts

Webhook dashboard には、配信失敗時の email alert 機能はありません。配信を監視するには、Developer → Webhooks に移動し、Logs tab と Activity tab を確認してください。

Cloud Platform への Deploy

一般的な cloud provider に Webhook handler を deploy するための platform-specific guide:

Vercel

serverless function を使用して Vercel に Webhook を deploy

Cloudflare Workers

Cloudflare の edge network で Webhook を実行

Supabase Edge Functions

Webhook を Supabase と統合

Netlify Functions

Netlify serverless function として Webhook を deploy

関連 API Reference

Create Webhook

Webhook endpoint を programmatically に作成・設定

List Webhooks

Webhook endpoint を取得・管理
最終更新日 2026年9月26日