Webhooksは、Dodo Paymentsアカウントで特定のイベントが発生した際に、リアルタイム通知を提供します。Webhooksを使用してワークフローの自動化、データベースの更新、通知の送信、システムの同期を行えます。
主な機能
Real-time Delivery
イベント発生時に即座に通知を受信
Secure by Default
HMAC SHA256署名の検証に対応
Automatic Retries
指数バックオフによる組み込みの再試行ロジック
Event Filtering
必要なイベントのみを購読
はじめに
Access Webhook Settings
DodoPayments Dashboardに移動し、Developer > Webhooksに進みます。
Create Webhook Endpoint
Add Webhookをクリックして、新しいWebhookエンドポイントを作成します。Add Endpoint URL
Webhookイベントを受信するURLを入力します。
Select Events to Receive
イベントリストから選択して、Webhookエンドポイントがリッスンする特定のイベントを選びます。選択したイベントのみがエンドポイントへのWebhookを発火するため、不要なトラフィックや処理を回避できます。
Get Secret Key
設定ページからWebhookのSecret Keyを取得します。受信したWebhookの真正性を検証するために使用します。Webhook secret keyは安全に保管し、クライアント側のコードや公開リポジトリに決して公開しないでください。
Rotate Secret (Optional)
必要に応じて、セキュリティを強化するためにWebhook secretをローテーションできます。Webhook設定でRotate Secretボタンをクリックします。Secretをローテーションすると、現在のsecretは期限切れとなり、新しいsecretに置き換えられます。古いsecretはその後24時間のみ有効です。それ以降、古いsecretで検証すると失敗します。
Secretのローテーションは定期的に行うか、現在のsecretが漏えいした可能性がある場合は直ちに行ってください。
購読イベントの設定
各Webhookエンドポイントで受信する特定のイベントを設定できます。
イベント設定へのアクセス
Navigate to Webhook Details
Dodo Payments Dashboardに移動し、Developer > Webhooksに進みます。
Select Your Endpoint
設定するWebhookエンドポイントをクリックします。
Open Event Settings
Webhook詳細ページに「Subscribed events」セクションがあります。Editボタンをクリックしてイベント購読を変更します。
イベント購読の管理
View Available Events
インターフェースには、利用可能なすべてのWebhookイベントが階層構造で表示されます。イベントはカテゴリ(例:dispute、payment、subscription)ごとに分類されます。
Search and Filter
検索バーにイベント名やキーワードを入力して、特定のイベントをすばやく検索します。
Select Events
受信するイベントの横にあるチェックボックスをオンにします。次の操作ができます。
- 個別のサブイベントを選択(例:
dispute.accepted、dispute.challenged)
- 親イベントを選択して、関連するすべてのサブイベントを受信
- 必要に応じて特定のイベントを組み合わせて選択
Review Event Details
各イベントの横にある情報アイコン(ⓘ)にカーソルを合わせると、そのイベントが発火する条件の説明が表示されます。
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仕様に従って署名を自分で検証できます。
webhook-id、webhook-timestamp、正確なraw stringified payloadをピリオド(.)で連結し、署名対象メッセージを作成します。
- DashboardのWebhook secret keyを使用して、その文字列のHMAC SHA256を計算します。
- 計算したsignatureと
webhook-signature headerを比較します。一致すれば、Webhookは正当なものです。
Webhooksへの応答
- Webhook handlerは、イベントの受信を確認するために
2xx status codeを返す必要があります。
- その他のresponseは失敗として扱われ、Webhookが再試行されます。
ベストプラクティス
Webhook endpointには必ずHTTPS URLを使用してください。HTTP endpointは中間者攻撃に対して脆弱で、Webhook dataが露出します。
webhook-id headerを使用して冪等性を実装し、同じイベントを副作用なく複数回安全に処理できるようにします。
Secure your webhook secret
環境変数またはsecrets managerを使用してWebhook secretを安全に保管してください。secretをバージョン管理にコミットしないでください。
Webhook Payloadの構造
Webhook payloadの構造を理解すると、イベントを正しく解析して処理できます。
Request形式
このWebhookイベントの一意な識別子。冪等性チェックに使用します。
Webhookの真正性を検証するためのHMAC SHA256 signature。
Webhookが送信された時刻を示すUnix timestamp(秒単位)。
Request Body
Dodo Paymentsのbusiness identifier。
このWebhookを発火させたイベントタイプ(例:payment.succeeded、subscription.active)。
イベントが発生した時刻のISO 8601形式のtimestamp。
イベントの詳細情報を含む、イベント固有のpayload。表示 Data object properties
リソースのタイプ。次のいずれかです:Payment、Subscription、Refund、Dispute、LicenseKey、CreditLedgerEntry、CreditBalanceLow、AbandonedCheckout、DunningAttempt、またはEntitlementGrant。
その他のフィールドはイベントタイプによって異なります。完全なスキーマについては、イベント固有のドキュメントを参照してください。
Payloadの例
Event Types
利用可能なすべてのWebhookイベントタイプを参照
Event Payloads
各イベントの詳細なpayloadスキーマを確認
Handle Payment Failures
payment.failedに対応し、declined paymentを復旧
Webhooksのテスト
本番稼働前にエンドポイントが正しく動作することを確認するため、Dodo Payments dashboardからWebhook integrationを直接テストできます。
テストインターフェースへのアクセス
Navigate to Webhooks
Dodo Payments Dashboardに移動し、Developer > Webhooksに進みます。
Select Your Endpoint
Webhookエンドポイントをクリックして詳細ページを開きます。
Open Testing Tab
TestingタブをクリックしてWebhookテストインターフェースを開きます。
Webhookのテスト
テストインターフェースでは、Webhookエンドポイントを包括的にテストできます。
Select Event Type
ドロップダウンメニューから、テストするイベントタイプ(例:payment.succeeded、payment.failedなど)を選択します。ドロップダウンには、エンドポイントが受信できるすべてのWebhookイベントタイプが含まれます。
Review Schema and Example
選択したイベントタイプのSchema(データ構造)とExample(サンプルpayload)が表示されます。
Send Test Event
Send Exampleボタンをクリックして、テストWebhookをエンドポイントに送信します。重要:テストインターフェースから送信された失敗メッセージは再試行されません。これはテスト専用です。
テストの検証
Check Your Endpoint
Webhookエンドポイントのログを監視して、テストイベントを受信したことを確認します。
Verify Signature
テストpayloadでsignature verificationが正しく動作していることを確認します。
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イベントがエンドポイントに配信される頻度を制御し、システムへの過負荷を防ぎます。
Access Rate Limit Settings
Advancedタブで「Rate Limit (throttling)」セクションを探します。
Configure Rate Limit
Editボタンをクリックしてrate limit settingsを変更します。デフォルトでは「No rate limit」が適用され、イベントは発生するとすぐに配信されます。
Set Limits
希望するrate limitを設定してWebhookの配信頻度を制御し、システムの過負荷を防ぎます。
Webhook handlerでイベント処理に時間が必要な場合や、複数のイベントをまとめて処理したい場合はrate limitingを使用します。
エンドポイントに送信されるすべてのWebhook requestにcustom HTTP headersを追加します。認証、routing、Webhook requestへのmetadata追加に便利です。
Add Custom Header
「Custom Headers」セクションで、custom headerのKeyとValueを入力します。
Add Multiple Headers
必要に応じて**+**ボタンをクリックし、custom headersを追加します。
Save Configuration
custom headersは、このエンドポイントへのすべてのWebhook requestに含まれます。
Transformationsを使用すると、Webhookのpayloadを変更して別のURLへリダイレクトできます。この強力な機能により、次のことが可能です。
- 処理前にpayloadの構造を変更
- 内容に基づいてWebhookを異なるendpointへルーティング
- payloadへのフィールドの追加または削除
- data形式の変換
Enable Transformations
Enabledスイッチをオンにしてtransformation機能を有効にします。
Configure Transformation
Edit transformationをクリックしてtransformation rulesを定義します。JavaScriptを使用してWebhook payloadを変換し、異なるtarget URLを指定できます。
Test Transformation
本番稼働前にtesting interfaceでtransformationが正しく動作することを確認します。
TransformationsはWebhook配信のパフォーマンスに大きな影響を与える可能性があります。十分にテストし、transformation logicをシンプルかつ効率的に保ってください。
Transformationsは特に次の用途に便利です。
- 異なるdata形式間の変換
- 特定の条件に基づくイベントのフィルタリング
- payloadへの計算フィールドの追加
- イベントの異なるmicroservicesへのルーティング
Webhook Logsの監視
Logsタブでは、Webhook配信ステータスを包括的に確認でき、Webhookイベントを効率的に監視、デバッグ、管理できます。
Activityの監視
Activityタブでは、visual analyticsを通じてWebhook配信パフォーマンスをリアルタイムに把握できます。
Email Alerts
自動メール通知でWebhookの状態を把握できます。Webhook配信が失敗し始めたり、エンドポイントが応答しなくなったりすると、問題にすばやく対処してintegrationsを円滑に維持できるよう、メールアラートが届きます。
Email Alertsを有効にする
Navigate to Alerting Settings
Dodo Payments Dashboardに移動し、Dashboard → Webhooks → Alertingに進みます。
Enable Email Notifications
Email notificationsをオンにして、Webhook配信の問題に関するアラートの受信を開始します。
Configure Email Address
Webhook alertsを受信するメールアドレスを入力します。Webhook setupで特定のイベントが発生した際、integrationsに影響する可能性がある配信問題などについて、このアドレスに通知を送信します。
Email alertsを有効にしてWebhook配信の問題を早期に検知し、信頼性の高いintegrationsを維持してください。配信に失敗した場合やエンドポイントが応答しなくなった場合に通知されます。
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リファレンス