
私たちのWebhook実装は、Standard Webhooks仕様に従っており、業界のベストプラクティスおよび既存のWebhookライブラリとの互換性を確保しています。
主な機能
リアルタイム配信
イベントが発生したときに即時通知を受け取ります
デフォルトで安全
HMAC SHA256署名検証が含まれています
自動再試行
指数バックオフを伴う組み込みの再試行ロジック
イベントフィルタリング
必要なイベントのみにサブスクライブします
始めに
1
Webhook設定にアクセスする
DodoPaymentsダッシュボードに移動し、
Settings > Webhooksに進みます。2
Webhookエンドポイントを作成する
Add Webhookをクリックして新しいWebhookエンドポイントを作成します。
3
エンドポイントURLを追加する
Webhookイベントを受信したいURLを入力します。
4
受信するイベントを選択する
イベントリストからWebhookエンドポイントがリッスンする特定のイベントを選択します。
5
秘密鍵を取得する
設定ページからWebhookの
Secret Keyを取得します。これを使用して受信したWebhookの真正性を確認します。6
秘密を回転させる(オプション)
必要に応じて、セキュリティを強化するためにWebhook秘密を回転させることができます。Webhook設定で秘密を回転させるボタンをクリックします。
現在の秘密が侵害された疑いがある場合は、定期的にまたは直ちに秘密の回転を使用してください。
サブスクライブしたイベントの設定
各Webhookエンドポイントが受信したい特定のイベントを設定できます。イベント設定へのアクセス
1
Webhookの詳細に移動する
Dodo Paymentsダッシュボードに移動し、
Settings > Webhooksに進みます。2
エンドポイントを選択する
設定したいWebhookエンドポイントをクリックします。
3
イベント設定を開く
Webhookの詳細ページで、「サブスクライブしたイベント」セクションが表示されます。編集ボタンをクリックしてイベントのサブスクリプションを変更します。
イベントサブスクリプションの管理
1
利用可能なイベントを表示する
インターフェースは、階層構造で整理されたすべての利用可能なWebhookイベントを表示します。イベントはカテゴリごとにグループ化されています(例:
dispute、payment、subscription)。2
検索とフィルタリング
検索バーを使用して、イベント名やキーワードを入力して特定のイベントを迅速に見つけます。
3
イベントを選択する
受信したいイベントの隣にあるチェックボックスをオンにします。次のことができます:
- 個々のサブイベントを選択する(例:
dispute.accepted、dispute.challenged) - 親イベントを選択して、関連するすべてのサブイベントを受信する
- 必要に応じて特定のイベントをミックス&マッチする
4
イベントの詳細を確認する
各イベントの隣にある情報アイコン(ⓘ)にカーソルを合わせると、そのイベントがトリガーされる条件の説明が表示されます。
5
設定を保存する
保存をクリックして変更を適用するか、キャンセルをクリックして変更を破棄します。
Webhook配信
タイムアウト
Webhookには、接続および読み取り操作のための15秒のタイムアウトウィンドウがあります。タイムアウトを避けるために、エンドポイントが迅速に応答することを確認してください。自動再試行
Webhook配信が失敗した場合、Dodo Paymentsはシステムを圧倒しないように指数バックオフで自動的に再試行します。| 試行 | 遅延 | 説明 |
|---|---|---|
| 1 | すぐに | 最初の再試行はすぐに行われます |
| 2 | 5秒 | 短い遅延の後に2回目の試行 |
| 3 | 5分 | 増加したバックオフで3回目の試行 |
| 4 | 30分 | バックオフを続けて4回目の試行 |
| 5 | 2時間 | 延長された遅延で5回目の試行 |
| 6 | 5時間 | より長い遅延で6回目の試行 |
| 7 | 10時間 | 最大遅延で7回目の試行 |
| 8 | 10時間 | 最終試行 - 失敗した場合はWebhookが失敗としてマークされます |
Webhookイベントごとに最大8回の再試行が行われます。たとえば、Webhookが成功する前に3回失敗した場合、最初の試行からの合計配信時間は約35分5秒です。
冪等性
各Webhookイベントには一意のwebhook-idヘッダーが含まれています。この識別子を使用して冪等性を実装し、重複処理を防ぎます。
イベントの順序
Webhookイベントは、再試行やネットワーク条件により順不同で到着する場合があります。システムを設計して、任意の順序でイベントを処理できるようにしてください。Webhookイベントが元々発生した時期に関係なく、配信時の最新のペイロードを受け取ります。
Webhookのセキュリティ
Webhookのセキュリティを確保するために、常にペイロードを検証し、HTTPSを使用してください。署名の検証
各Webhookリクエストには、WebhookペイロードとタイムスタンプのHMAC SHA256署名を含むwebhook-signatureヘッダーが含まれています。これはあなたの秘密鍵で署名されています。
SDK検証(推奨)
すべての公式SDKには、受信したWebhookを安全に検証および解析するための組み込みヘルパーが含まれています。2つのメソッドが利用可能です:unwrap():Webhook秘密鍵を使用して署名を検証しますunsafe_unwrap():検証なしでペイロードを解析します
手動検証(代替)
SDKを使用していない場合は、Standard Webhooks仕様に従って署名を自分で検証できます:webhook-id、webhook-timestamp、正確な生の文字列化されたpayloadをピリオド(.)で区切って連結して署名メッセージを構築します。- ダッシュボードからのWebhook秘密鍵を使用して、その文字列のHMAC SHA256を計算します。
- 計算された署名を
webhook-signatureヘッダーと比較します。一致すれば、Webhookは本物です。
私たちはStandard Webhooks仕様に従っています。署名を検証するために彼らのライブラリを使用できます:https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries。イベントペイロード形式については、Webhookペイロードを参照してください。
Webhookへの応答
- Webhookハンドラーは、イベントの受信を確認するために
2xx status codeを返す必要があります。 - その他の応答は失敗と見なされ、Webhookは再試行されます。
ベストプラクティス
HTTPSエンドポイントのみを使用
HTTPSエンドポイントのみを使用
Webhookエンドポイントには常にHTTPS URLを使用してください。HTTPエンドポイントは中間者攻撃に対して脆弱であり、Webhookデータを公開します。
即座に応答する
即座に応答する
Webhookを受信したら、すぐに
200ステータスコードを返します。タイムアウトを避けるために、イベントを非同期に処理します。重複イベントを処理する
重複イベントを処理する
webhook-idヘッダーを使用して冪等性を実装し、副作用なしで同じイベントを複数回安全に処理します。Webhook秘密を保護する
Webhook秘密を保護する
環境変数やシークレットマネージャーを使用してWebhook秘密を安全に保管します。決してシークレットをバージョン管理にコミットしないでください。
Webhookペイロード構造
Webhookペイロード構造を理解することで、イベントを正しく解析し処理できます。リクエスト形式
ヘッダー
このWebhookイベントの一意の識別子。冪等性チェックに使用します。
Webhookの真正性を検証するためのHMAC SHA256署名。
Webhookが送信されたときのUnixタイムスタンプ(秒単位)。
リクエストボディ
あなたのDodo Paymentsビジネス識別子。
このWebhookをトリガーしたイベントタイプ(例:
payment.succeeded、subscription.created)。イベントが発生した時刻のISO 8601形式のタイムスタンプ。
イベントに特有のペイロードで、イベントに関する詳細情報を含みます。
例のペイロード
Webhookのテスト
Dodo Paymentsダッシュボードから直接Webhook統合をテストして、エンドポイントが正しく機能していることを確認できます。
テストインターフェースへのアクセス
1
Webhookに移動する
Dodo Paymentsダッシュボードに移動し、
Settings > Webhooksに進みます。2
エンドポイントを選択する
Webhookエンドポイントをクリックして、その詳細ページにアクセスします。
3
テストタブを開く
テストタブをクリックしてWebhookテストインターフェースにアクセスします。
Webhookをテストする
テストインターフェースは、Webhookエンドポイントをテストするための包括的な方法を提供します:1
イベントタイプを選択する
ドロップダウンメニューを使用して、テストしたい特定のイベントタイプを選択します(例:
payment.succeeded、payment.failedなど)。ドロップダウンには、エンドポイントが受信できるすべての利用可能なWebhookイベントタイプが含まれています。
2
スキーマと例を確認する
インターフェースは、選択したイベントタイプのスキーマ(データ構造)と例(サンプルペイロード)を表示します。
3
テストイベントを送信する
例を送信ボタンをクリックして、エンドポイントにテストWebhookを送信します。
テストの確認
1
エンドポイントを確認する
Webhookエンドポイントのログを監視して、テストイベントが受信されたことを確認します。
2
署名を検証する
テストペイロードで署名検証が正しく機能していることを確認します。
3
レスポンスをテストする
エンドポイントがイベントの受信を確認するために
2xxステータスコードを返すことを確認します。実装例
Webhookの検証と処理を示す完全なExpress.js実装は次のとおりです:高度な設定
高度な設定タブでは、Webhookエンドポイントの動作を微調整するための追加の構成オプションを提供します。レート制限(スロットリング)
Webhookイベントがエンドポイントに配信されるレートを制御して、システムが圧倒されないようにします。1
レート制限設定にアクセスする
高度なタブで、「レート制限(スロットリング)」セクションを見つけます。
2
レート制限を設定する
編集ボタンをクリックしてレート制限設定を変更します。
デフォルトでは、Webhookには「レート制限なし」が適用されており、イベントは発生次第配信されます。
3
制限を設定する
Webhook配信の頻度を制御し、システムの過負荷を防ぐために、希望するレート制限を設定します。
カスタムヘッダー
すべてのWebhookリクエストにカスタムHTTPヘッダーを追加します。これは、認証、ルーティング、またはWebhookリクエストにメタデータを追加するのに便利です。1
カスタムヘッダーを追加する
「カスタムヘッダー」セクションで、カスタムヘッダーのキーと値を入力します。
2
複数のヘッダーを追加する
必要に応じて、**+**ボタンをクリックして追加のカスタムヘッダーを追加します。
3
設定を保存する
あなたのカスタムヘッダーは、このエンドポイントへのすべてのWebhookリクエストに含まれます。
変換
変換を使用すると、Webhookのペイロードを変更し、別のURLにリダイレクトできます。この強力な機能により、次のことが可能になります:- 処理前にペイロード構造を変更する
- コンテンツに基づいてWebhookを異なるエンドポイントにルーティングする
- ペイロードからフィールドを追加または削除する
- データ形式を変換する
1
変換を有効にする
有効スイッチを切り替えて、変換機能をアクティブにします。
2
変換を設定する
変換を編集をクリックして、変換ルールを定義します。
JavaScriptを使用してWebhookペイロードを変換し、異なるターゲットURLを指定できます。
3
変換をテストする
テストインターフェースを使用して、変換が正しく機能することを確認します。
Webhookログの監視
ログタブは、Webhook配信状況を包括的に可視化し、Webhookイベントを効果的に監視、デバッグ、管理できるようにします。
アクティビティモニタリング
アクティビティタブは、視覚的な分析を通じてWebhook配信パフォーマンスに関するリアルタイムの洞察を提供します。
メールアラート
Webhookの健康状態について自動メール通知で情報を得ることができます。Webhook配信が失敗し始めたり、エンドポイントが応答しなくなったりすると、メールアラートが届き、問題に迅速に対処して統合をスムーズに保つことができます。
メールアラートを有効にする
1
アラート設定に移動する
Dodo Paymentsダッシュボードに移動し、ダッシュボード → Webhooks → アラートに進みます。
2
メール通知を有効にする
メール通知をオンにして、Webhook配信の問題に関するアラートを受信し始めます。
3
メールアドレスを設定する
Webhookアラートを受信したいメールアドレスを入力します。Webhook設定に関する特定のイベントが発生したときに、このアドレスに通知を送信します。たとえば、統合に影響を与える可能性のある配信問題などです。
クラウドプラットフォームへのデプロイ
Webhookハンドラーを本番環境にデプロイする準備はできましたか?各プラットフォームのベストプラクティスに従って、人気のあるクラウドプロバイダーにWebhookをデプロイするためのプラットフォーム固有のガイドを提供します。Vercel
サーバーレス関数を使用してVercelにWebhookをデプロイします
Cloudflare Workers
CloudflareのエッジネットワークでWebhookを実行します
Supabase Edge Functions
SupabaseとWebhookを統合します
Netlify Functions
Netlifyサーバーレス関数としてWebhookをデプロイします
各プラットフォームガイドには、環境設定、署名検証、特定のプロバイダーに固有のデプロイ手順が含まれています。