
主な機能
Real-time Delivery
Secure by Default
Automatic Retries
Event Filtering
はじめに
- Developer → Webhooks の下 — Endpoints、Event catalog、Logs、Activity、Settings タブ。
- 個別のエンドポイント上 — 配信統計、署名シークレット、Replay history を含む Overview タブ、さらに Testing、Advanced タブと一括 replay アクション。
- メッセージ上 — Logs タブから開くと、エンドポイントを開かずに各配信試行を個別に replay できます。
Access Webhook Settings
Create Webhook Endpoint
Enter Endpoint URL or Choose Integration
Select Events to Receive
Create Endpoint
Get Secret Key
Rotate Secret (Optional)
Integration Connectors
独自の webhook receiver を構築する代わりに、integration connector を使用して webhook event をサードパーティサービスへ直接ルーティングできます。これにより、一般的なプラットフォーム向けにカスタム webhook handler を記述・保守する必要がなくなります。Connector の仕組み
connector は、Dodo Payments event を送信先が想定する形式に変換する処理を実行します。入力する詳細は送信先によって異なります。Connector の設定
エンドポイントの作成または編集時に connector を選択すると、サイドシートに送信先に合わせたセットアップ手順が表示されます。たとえば、Slack で incoming webhook URL を作成する方法や、Resend API key の確認場所などです。保存する前に connector transformation test を実行し、event が送信先向けに正しく変換されることを確認してください。Subscribed Events の設定
各 webhook endpoint が受信する特定のイベントを設定できます。Navigate to Webhook Endpoints
Select Your Endpoint
Open Event Configuration
Browse Event Types
payment、subscription、dispute)。検索バーを使用すると、名前やキーワードから特定のイベントをすばやく見つけられます。Select Events
- 個別のイベントを選択する(例:
payment.succeeded、payment.failed) - 親リソースを選択して関連するすべてのイベントを受信する
- 必要に応じて特定のイベントを組み合わせる
Save Configuration
Event Catalog
Developer → Webhooks に移動し、Event catalog タブを開きます。ここには Dodo Payments が送信できるすべてのイベントタイプが一覧表示されるため、エンドポイントを購読する前に利用可能なイベントを確認できます。イベントを選択すると、その schema とサンプル payload を表示できます。読み取る予定のフィールドの形式を確認する最も簡単な方法です。Webhook Events Guide
Webhook Delivery
タイムアウト
webhooks には、接続操作と読み取り操作の両方に 15 秒のタイムアウトウィンドウ があります。タイムアウトを避けるため、エンドポイントがすぐに応答するようにしてください。自動リトライ
webhook delivery が失敗すると、Dodo Payments は指数バックオフで自動的にリトライし、システムに過剰な負荷がかからないようにします。Idempotency
各 webhook event には一意のwebhook-id header が含まれます。この識別子を使用して idempotency を実装し、重複処理を防止してください。
イベント順序
リトライやネットワーク状況により、webhook event が順不同で届く場合があります。どの順序のイベントにも対応できるようにシステムを設計してください。Webhooks のセキュリティ保護
webhooks のセキュリティを確保するため、常に payload を検証し、HTTPS を使用してください。署名の検証
各 webhook request にはwebhook-signature header が含まれます。これは webhook payload と timestamp の HMAC SHA256 signature で、secret key によって署名されています。
SDK verification(推奨)
すべての公式 SDK には、受信した webhooks を安全に検証・解析するための built-in helper が含まれています。利用できる方法は 2 つです。unwrap(): webhook secret key を使用して signature を検証しますunsafe_unwrap(): verification なしで payload を解析します
Manual verification(代替方法)
SDK を使用していない場合は、Standard Webhooks spec に従って自分で signature を検証できます。webhook-id、webhook-timestamp、正確な raw stringifiedpayloadをピリオド(.)で区切って連結し、署名対象メッセージを作成します。- Dashboard の webhook secret key を使用して、その文字列の HMAC SHA256 を計算します。
- 計算した signature と
webhook-signatureheader を比較します。一致すれば webhook は authentic です。
ソース IP アドレス
Webhook を認証するために推奨されている方法は、署名検証です。これにより、リクエストが webhook secret を使って署名されたことを証明できますが、ネットワークレベルのチェックではそれを確認できません。 Webhook の配信は、当社の配信インフラストラクチャに属するソース IP アドレスのプールから送信されます。このプールは随時変更されるため、アドレスは統合の固定された特性ではなく、運用上の詳細として扱ってください。 ファイアウォールの背後にインフラストラクチャがあり、明示的な allowlist が必要な場合は、次の点に注意してください。- アドレスを恒久的にハードコードしないでください。 範囲は時間の経過とともに追加・廃止されるため、古いルールによって配信が気付かないうちにブロックされます。
- ファイアウォールを制限する前に、support@dodopayments.com から現在の範囲をリクエストしてください。最新のリストに基づいて作業できます。
- 変更通知を確認してください。 配信アドレスが変更される場合、影響を受ける Merchant にはメールで通知します。配信の欠落を避けるため、指定された日付までに更新を適用してください。
- 追加するネットワークルールにかかわらず、署名検証を有効にしておいてください。
Webhook への応答
- webhook handler は、イベントを受信したことを確認するために
2xx status codeを返す必要があります。 - その他のレスポンスは失敗として扱われ、webhook は再試行されます。
ベストプラクティス
Use HTTPS endpoints only
Use HTTPS endpoints only
Respond immediately
Respond immediately
200 status code を返してください。タイムアウトを避けるため、イベントは非同期で処理します。Handle duplicate events
Handle duplicate events
webhook-id header を使用して idempotency を実装し、副作用なしに同じイベントを複数回安全に処理できるようにしてください。Secure your webhook secret
Secure your webhook secret
Webhook Payload の構造
Webhook payload の構造を理解すると、イベントを正しく解析・処理できます。リクエスト形式
Headers
Request Body
payment.succeeded、subscription.active)。Payload の例
Event Types
Event Payloads
Handle Payment Failures
payment.failed に反応し、declined payment を回復Webhook のテスト
本番稼働前に endpoint が正しく動作することを確認するため、Dodo Payments dashboard から webhook 統合を直接テストできます。Navigate to Webhooks
Select Your Endpoint
Open Testing Tab
Example Event の送信
Testing tab はこの endpoint にサンプル payload を送信するため、receiver を検証できます。Select Event Type
payment.succeeded または payment.failed。Send Example
Check Your Endpoint
2xx status code を返したことを確認してください。実装例
webhook の検証と処理を示す、完全な Express.js 実装を次に示します。CLI を使用した Webhook のテスト
Dodo Payments CLI には、terminal を離れることなく local development 中に webhook をテストできる 2 つのコマンドがあります。Live Webhook をローカルでリッスンする
test mode account から実際の webhook event を local development server にリアルタイムで転送します。http://localhost:3000/webhook)に転送します。検証テスト用の signature headers を含む、すべての headers が保持されます。
dodo login を実行し、Test Mode を選択してください。Mock Webhook Event をトリガーする
実際の transaction を作成せずに、任意の endpoint へ mock webhook payload を送信します。CLI Webhook Testing Docs
Advanced Settings
Advanced tab には、webhook endpoint の動作を細かく調整するための追加設定オプションがあります。Rate Limiting(Throttling)
システムへの過負荷を防ぐため、webhook event が endpoint に配信される速度を制御します。Open Advanced Tab
Configure Rate Limit
Set Your Limit
Custom Headers
endpoint に送信するすべての webhook request に custom HTTP headers を追加します。認証、routing、または metadata の追加に便利です。Add Headers
Add Multiple Headers
Transformations
Transformations を使用すると、webhook の payload を変更し、必要に応じて別の URL にリダイレクトできます。この強力な機能により、次のことが可能になります。- 処理前に payload の構造を変更する
- 内容に基づいて webhook を異なる endpoint に routing する
- payload のフィールドを追加または削除する
- data format を変換する
Enable Transformations
Configure Transformation
Test Transformation
Webhook Logs の監視
Logs tab では webhook delivery status を包括的に確認でき、webhook event を効果的に監視、デバッグ、管理できます。Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 完全な webhook payload
- response code と duration を含むすべての delivery attempt
- 各 attempt の timestamp
- endpoint から返されたエラーメッセージ
Activity Monitoring
Developer → Webhooks に移動し、Activity tab を開くと、各 endpoint の delivery performance を確認できます。 Delivery activity では、期間に応じて Attempts per 5 minutes、Attempts per hour、または Attempts per day として分類された attempt の推移を表示します。各バーは結果別に分割され、セグメントにカーソルを合わせると status、attempt 数、全体に占める割合が表示されます。endpoint の Overview tab にある Delivery stats (last 24h) では、過去 1 日分の同じ情報をまとめて確認できます。Message の再生と復旧
message を再配信する方法は、必要な数によって異なります。- 1 件の message — Logs tab から message を開き、attempt の Replay action を使用します。endpoint を開く必要はありません。
- 複数の message の範囲 — bulk mode は一度に 1 つの endpoint に対して実行されるため、endpoint を開きます。
Bulk での再生
Developer → Webhooks から endpoint を開きます。3 つの mode が利用でき、それぞれその endpoint だけに対して実行されます。設定する範囲は mode によって異なります。Open More Actions
Set the Range
Start the Run
Email Alerts
endpoint への webhook delivery が失敗しているときに email notification を受け取り、問題が backlog になる前に対処できるようにします。Navigate to Settings Tab
Find Email Alerting
Configure Email Addresses
Save