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

Add Webhookをクリックして、新しいWebhookエンドポイントを作成します。
Add Webhook
3

Add Endpoint URL

Webhookイベントを受信するURLを入力します。
4

Select Events to Receive

イベントリストから選択して、Webhookエンドポイントがリッスンする特定のイベントを選びます。
選択したイベントのみがエンドポイントへのWebhookを発火するため、不要なトラフィックや処理を回避できます。
5

Get Secret Key

設定ページからWebhookのSecret Keyを取得します。受信したWebhookの真正性を検証するために使用します。
Webhook secret keyは安全に保管し、クライアント側のコードや公開リポジトリに決して公開しないでください。
6

Rotate Secret (Optional)

必要に応じて、セキュリティを強化するためにWebhook secretをローテーションできます。Webhook設定でRotate Secretボタンをクリックします。
Secretをローテーションすると、現在のsecretは期限切れとなり、新しいsecretに置き換えられます。古いsecretはその後24時間のみ有効です。それ以降、古いsecretで検証すると失敗します。
Secretのローテーションは定期的に行うか、現在のsecretが漏えいした可能性がある場合は直ちに行ってください。

購読イベントの設定

各Webhookエンドポイントで受信する特定のイベントを設定できます。

イベント設定へのアクセス

1

Navigate to Webhook Details

Dodo Payments Dashboardに移動し、Developer > Webhooksに進みます。
2

Select Your Endpoint

設定するWebhookエンドポイントをクリックします。
3

Open Event Settings

Webhook詳細ページに「Subscribed events」セクションがあります。Editボタンをクリックしてイベント購読を変更します。

イベント購読の管理

1

View Available Events

インターフェースには、利用可能なすべてのWebhookイベントが階層構造で表示されます。イベントはカテゴリ(例:disputepaymentsubscription)ごとに分類されます。
2

Search and Filter

検索バーにイベント名やキーワードを入力して、特定のイベントをすばやく検索します。
3

Select Events

受信するイベントの横にあるチェックボックスをオンにします。次の操作ができます。
  • 個別のサブイベントを選択(例:dispute.accepteddispute.challenged
  • 親イベントを選択して、関連するすべてのサブイベントを受信
  • 必要に応じて特定のイベントを組み合わせて選択
4

Review Event Details

各イベントの横にある情報アイコン(ⓘ)にカーソルを合わせると、そのイベントが発火する条件の説明が表示されます。
5

Save Configuration

Saveをクリックして変更を適用するか、Cancelをクリックして変更を破棄します。
すべてのイベントの選択を解除すると、Webhookエンドポイントは通知を受信しません。アプリケーションが正常に動作するために必要なイベントを少なくとも選択してください。

Webhookの配信

タイムアウト

Webhooksには、接続操作と読み取り操作の両方に15秒のタイムアウトウィンドウがあります。タイムアウトを避けるため、エンドポイントがすばやく応答するようにしてください。
Webhookは、200 status codeですぐに受信を確認してから、実際の処理をバックグラウンドで行う非同期方式で処理してください。

自動再試行

Webhookの配信に失敗すると、Dodo Paymentsは指数バックオフで自動的に再試行し、システムへの過負荷を防ぎます。
Webhookイベントごとの再試行は最大8回です。たとえば、Webhookが成功するまでに3回失敗した場合、最初の試行からの合計配信時間は約35分5秒です。
Dodo Payments dashboardを使用すると、個々のメッセージを手動で再試行したり、失敗したすべてのメッセージを一括でいつでも復旧したりできます。

冪等性

各Webhookイベントには一意のwebhook-id headerが含まれます。この識別子を使用して冪等性を実装し、重複処理を防止します。
必ず冪等性チェックを実装してください。再試行により、同じイベントを複数回受信する可能性があります。

イベントの順序

再試行やネットワーク状況により、Webhookイベントが順不同で到着する場合があります。どの順序でもイベントを処理できるようにシステムを設計してください。
Webhookイベントが最初に発行された時刻にかかわらず、配信時点での最新のpayloadを受信します。

Webhooksのセキュリティ保護

Webhooksのセキュリティを確保するため、必ずpayloadを検証し、HTTPSを使用してください。

署名の検証

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

SDKによる検証(推奨)

すべての公式SDKには、受信したWebhookを安全に検証して解析するための組み込みヘルパーが含まれています。利用できるメソッドは2つです。
  • unwrap():Webhook secret keyを使用して署名を検証
  • unsafe_unwrap():検証せずにpayloadを解析
Dodo Payments clientの初期化時に、DODO_PAYMENTS_WEBHOOK_KEYでWebhook secretを指定します。

手動検証(代替方法)

SDKを使用しない場合は、Standard Webhooks仕様に従って署名を自分で検証できます。
  1. webhook-idwebhook-timestamp、正確なraw stringified payloadをピリオド(.)で連結し、署名対象メッセージを作成します。
  2. DashboardのWebhook secret keyを使用して、その文字列のHMAC SHA256を計算します。
  3. 計算したsignatureとwebhook-signature headerを比較します。一致すれば、Webhookは正当なものです。
Standard Webhooks仕様に準拠しています。署名の検証には、次のライブラリを使用できます:https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries。イベントpayloadの形式については、Webhook Payloadを参照してください。

Webhooksへの応答

  • Webhook handlerは、イベントの受信を確認するために2xx status codeを返す必要があります。
  • その他のresponseは失敗として扱われ、Webhookが再試行されます。

ベストプラクティス

Webhook endpointには必ずHTTPS URLを使用してください。HTTP endpointは中間者攻撃に対して脆弱で、Webhook dataが露出します。
Webhookの受信時に200 status codeを直ちに返します。タイムアウトを避けるため、イベントを非同期で処理します。
webhook-id headerを使用して冪等性を実装し、同じイベントを副作用なく複数回安全に処理できるようにします。
環境変数またはsecrets managerを使用してWebhook secretを安全に保管してください。secretをバージョン管理にコミットしないでください。

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.succeededsubscription.active)。
string
必須
イベントが発生した時刻のISO 8601形式のtimestamp。
object
必須
イベントの詳細情報を含む、イベント固有のpayload。

Payloadの例

Event Types

利用可能なすべてのWebhookイベントタイプを参照

Event Payloads

各イベントの詳細なpayloadスキーマを確認

Handle Payment Failures

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

Webhooksのテスト

本番稼働前にエンドポイントが正しく動作することを確認するため、Dodo Payments dashboardからWebhook integrationを直接テストできます。
Endpoint Details

テストインターフェースへのアクセス

1

Navigate to Webhooks

Dodo Payments Dashboardに移動し、Developer > Webhooksに進みます。
2

Select Your Endpoint

Webhookエンドポイントをクリックして詳細ページを開きます。
3

Open Testing Tab

TestingタブをクリックしてWebhookテストインターフェースを開きます。

Webhookのテスト

テストインターフェースでは、Webhookエンドポイントを包括的にテストできます。
1

Select Event Type

ドロップダウンメニューから、テストするイベントタイプ(例:payment.succeededpayment.failedなど)を選択します。
ドロップダウンには、エンドポイントが受信できるすべてのWebhookイベントタイプが含まれます。
2

Review Schema and Example

選択したイベントタイプのSchema(データ構造)とExample(サンプルpayload)が表示されます。
3

Send Test Event

Send Exampleボタンをクリックして、テストWebhookをエンドポイントに送信します。
重要:テストインターフェースから送信された失敗メッセージは再試行されません。これはテスト専用です。

テストの検証

1

Check Your Endpoint

Webhookエンドポイントのログを監視して、テストイベントを受信したことを確認します。
2

Verify Signature

テストpayloadでsignature verificationが正しく動作していることを確認します。
3

Test Response

受信を確認するため、エンドポイントが2xx status codeを返すことを確認します。

実装例

Webhookの検証と処理を示す、完全なExpress.js実装例です。
本番イベントを処理する前に、dashboardのテストインターフェースを使用してWebhook handlerを十分にテストしてください。これにより、問題を早期に特定して修正できます。

CLIでのWebhooksのテスト

Dodo Payments CLIには、ターミナルを離れずにローカル開発中のWebhooksをテストするための2つのコマンドがあります。

ローカルでライブWebhookをリッスン

test mode accountから実際のWebhookイベントをローカル開発サーバーへリアルタイムに転送します。
CLIはDodo PaymentsへのWebSocket接続を開き、すべてのWebhookイベントをローカルエンドポイント(例:http://localhost:3000/webhook)に転送します。検証テスト用にsignature headersを含むすべてのheadersが保持されます。
listenerはtest mode API keysでのみ動作します。このコマンドを使用する前にdodo loginを実行し、Test Modeを選択してください。

モックWebhookイベントを発火

実際のtransactionを作成せずに、任意のエンドポイントへモックWebhook payloadを送信します。
このinteractive toolでは、サポートされているすべてのイベントタイプから選択し、現実的なモックpayloadをエンドポイントへ送信できます。ループするため、1回のセッションで複数のイベントをテストできます。
dodo wh triggerからのモックWebhook payloadには署名がありません。テスト時のWebhook handlerでは、unwrap()ではなくunsafe_unwrap()を使用してください。

CLI Webhook Testing Docs

CLI webhook testingの完全なドキュメントを参照

詳細設定

Advanced Settingsタブでは、Webhookエンドポイントの動作を細かく調整するための追加設定を利用できます。

Rate Limiting(スロットリング)

Webhookイベントがエンドポイントに配信される頻度を制御し、システムへの過負荷を防ぎます。
1

Access Rate Limit Settings

Advancedタブで「Rate Limit (throttling)」セクションを探します。
2

Configure Rate Limit

Editボタンをクリックしてrate limit settingsを変更します。
デフォルトでは「No rate limit」が適用され、イベントは発生するとすぐに配信されます。
3

Set Limits

希望するrate limitを設定してWebhookの配信頻度を制御し、システムの過負荷を防ぎます。
Webhook handlerでイベント処理に時間が必要な場合や、複数のイベントをまとめて処理したい場合はrate limitingを使用します。

Custom Headers

エンドポイントに送信されるすべてのWebhook requestにcustom HTTP headersを追加します。認証、routing、Webhook requestへのmetadata追加に便利です。
1

Add Custom Header

「Custom Headers」セクションで、custom headerのKeyValueを入力します。
2

Add Multiple Headers

必要に応じて**+**ボタンをクリックし、custom headersを追加します。
3

Save Configuration

custom headersは、このエンドポイントへのすべてのWebhook requestに含まれます。

Transformations

Transformationsを使用すると、Webhookのpayloadを変更して別のURLへリダイレクトできます。この強力な機能により、次のことが可能です。
  • 処理前にpayloadの構造を変更
  • 内容に基づいてWebhookを異なるendpointへルーティング
  • payloadへのフィールドの追加または削除
  • data形式の変換
1

Enable Transformations

Enabledスイッチをオンにしてtransformation機能を有効にします。
2

Configure Transformation

Edit transformationをクリックしてtransformation rulesを定義します。
JavaScriptを使用してWebhook payloadを変換し、異なるtarget URLを指定できます。
3

Test Transformation

本番稼働前にtesting interfaceでtransformationが正しく動作することを確認します。
TransformationsはWebhook配信のパフォーマンスに大きな影響を与える可能性があります。十分にテストし、transformation logicをシンプルかつ効率的に保ってください。
Transformationsは特に次の用途に便利です。
  • 異なるdata形式間の変換
  • 特定の条件に基づくイベントのフィルタリング
  • payloadへの計算フィールドの追加
  • イベントの異なるmicroservicesへのルーティング

Webhook Logsの監視

Logsタブでは、Webhook配信ステータスを包括的に確認でき、Webhookイベントを効率的に監視、デバッグ、管理できます。
Logs

Activityの監視

Activityタブでは、visual analyticsを通じてWebhook配信パフォーマンスをリアルタイムに把握できます。
Activity

Email Alerts

自動メール通知でWebhookの状態を把握できます。Webhook配信が失敗し始めたり、エンドポイントが応答しなくなったりすると、問題にすばやく対処してintegrationsを円滑に維持できるよう、メールアラートが届きます。
Webhook Alerting Settings showing email notifications configuration

Email Alertsを有効にする

1

Navigate to Alerting Settings

Dodo Payments Dashboardに移動し、Dashboard → Webhooks → Alertingに進みます。
2

Enable Email Notifications

Email notificationsをオンにして、Webhook配信の問題に関するアラートの受信を開始します。
3

Configure Email Address

Webhook alertsを受信するメールアドレスを入力します。Webhook setupで特定のイベントが発生した際、integrationsに影響する可能性がある配信問題などについて、このアドレスに通知を送信します。
Email alertsを有効にしてWebhook配信の問題を早期に検知し、信頼性の高いintegrationsを維持してください。配信に失敗した場合やエンドポイントが応答しなくなった場合に通知されます。

Cloud Platformsへのデプロイ

Webhook handlerをproductionにデプロイする準備はできましたか?各platformのベストプラクティスに基づき、主要なcloud providerへWebhooksをデプロイするためのplatform別ガイドを提供しています。

Vercel

serverless functionsを使用してVercelへWebhooksをデプロイ

Cloudflare Workers

Cloudflareのedge network上でWebhooksを実行

Supabase Edge Functions

WebhooksをSupabaseと統合

Netlify Functions

WebhooksをNetlify serverless functionsとしてデプロイ
各platform guideには、そのproviderに固有のenvironment setup、signature verification、deployment stepsが含まれています。

関連APIリファレンス

Create Webhook

Webhook endpointsをプログラムで作成・設定するためのAPIリファレンス

List Webhooks

Webhook endpointsを取得・管理するためのAPIリファレンス
最終更新日 2026年7月31日