
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
Event Payloads
Handle Payment Failures
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
詳細設定
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 をクリックします。