
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タブに表示されます。
Integration Connectors
統合コネクタを使用してwebhookイベントをサードパーティサービスへ直接ルーティングし、カスタムwebhookハンドラーを構築・保守する必要をなくします。コネクタの仕組み
コネクタは、Dodo Paymentsのイベントを送信先が想定する形式に変換します。入力する詳細情報は送信先によって異なります。
ダッシュボードには、ビジネスで利用可能なすべてのコネクタが表示されます。各送信先でイベントをどのように利用できるかについては、External Integrationsを参照してください。
コネクタの設定
エンドポイントの作成または編集時にコネクタを選択すると、サイドシートに送信先の設定手順が表示されます。保存する前に変換をテストして、イベントが正しく変換されることを確認してください。購読イベントの設定
各webhookエンドポイントが受信するイベントを設定します。1
Navigate to Webhook Endpoints
Developer → Webhooksに移動し、エンドポイントをクリックします。
2
Open Event Configuration
Editをクリックして、エンドポイント設定のサイドシートを開きます。
3
Select Events
イベントタイプセレクターには、リソース(例:
payment、subscription、dispute)ごとにグループ化された、検索可能なツリー形式のすべてのwebhookイベントが表示されます。受信するイベントの横にあるチェックボックスをオンにします。個別のイベント、リソース全体、またはそれらを組み合わせて選択できます。4
Save Configuration
Saveをクリックして変更を適用します。
イベントカタログ
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 を解析します。テスト専用です。
unwrap / unsafeUnwrap、Python では unwrap / unsafe_unwrap、Go では Unwrap / UnsafeUnwrap です。
手動検証(代替方法)
SDK を使用していない場合は、signature を自分で検証してください。webhook-id、webhook-timestamp、raw request body をピリオドで結合して、署名対象の content を作成します。{id}.{timestamp}.{body}。JSON parsing 前の、受信したままの raw body を使用してください。- webhook secret を取得します。
whsec_で始まる場合は、その prefix を削除し、残りを base64-decode して signing key を取得します。 - signing key を使用して署名対象 content の HMAC-SHA256 を計算し、結果を base64-encode します。
webhook-signatureheader には、v1,<base64-signature>形式の、スペース区切りの signature が 1 つ以上含まれます。いずれかのv1signature が自分の signature と一致すれば、request は有効です。constant-time function と比較してください。- replay attack を防ぐため、
webhook-timestampが現在時刻から大きく離れている場合は request を拒否します。Standard Webhooks libraries では 5 分が許容されています。
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 を有効にしたままにしてください。
ブロックされた配信は failure として扱われ、Automatic Retries に記載されたスケジュールで再試行されます。firewall rule によって配信が失敗した場合は、rule を修正した後に再送できます。Replaying and Recovering Messages を参照してください。
Webhook への応答
Webhook handler は、受信を確認するために2xx status code を返す必要があります。それ以外の response は failure として扱われ、Webhook が再試行されます。
ベストプラクティス
- HTTPS のみを使用してください。 HTTP endpoint は interception に対して脆弱です。
- 直ちに応答してください。
200status code をすぐに返し、その後イベントを非同期で処理します。 - 冪等性を実装してください。
webhook-idheader を使用して重複イベントを検出し、スキップします。 - 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:CLI を使用した Webhook のテスト
Dodo Payments CLI には、local development 中に Webhook をテストするための command が 2 つあります。Live Webhook をローカルでリッスンする
test mode account から local development server に実際の Webhook event を転送します。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 を送信します。subscription.past_due または subscription.unpaused は送信しません。正確な一覧については、Supported Webhook Events を参照してください。
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 が正しく動作することを確認します。
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
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 日分の同じ情報がまとめられます。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 をクリックします。
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 を取得・管理