
当社のWebhook実装はStandard Webhooks仕様に準拠しており、業界のベストプラクティスや既存のWebhookライブラリとの互換性を確保しています。
主な機能
Real-time Delivery
イベント発生時に即座に通知を受け取れます
Secure by Default
HMAC SHA256署名の検証を含みます
Automatic Retries
指数バックオフによる組み込みの再試行ロジック
Event Filtering
必要なイベントのみ購読できます
始めに
サブスクライブしたイベントの設定
各Webhookエンドポイントが受信したい特定のイベントを設定できます。イベント設定へのアクセス
イベントサブスクリプションの管理
View Available Events
インターフェースには利用可能なWebhookイベントが階層構造で表示されます。イベントはカテゴリー(例:
dispute、payment、subscription)ごとにグループ化されています。Select Events
受け取りたいイベントの横のチェックボックスにチェックを入れてください。次の操作が可能です:
- 個々のサブイベント(例:
dispute.accepted、dispute.challenged)を選択 - 親イベントを選択して関連するすべてのサブイベントを受信
- ニーズに応じて特定のイベントを組み合わせる
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秒かかります。
冪等性
Each webhook event includes a uniquewebhook-id header. Use this identifier to implement idempotency and prevent duplicate processing.
イベントの順序
Webhookイベントは、再試行やネットワーク条件により順不同で到着する場合があります。システムを設計して、任意の順序でイベントを処理できるようにしてください。イベントが実際に発行された時点に関係なく、配信時点での最新のペイロードが届きます。
Webhookのセキュリティ
Webhookのセキュリティを確保するために、常にペイロードを検証し、HTTPSを使用してください。署名の検証
Each webhook request includes awebhook-signature header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key.
SDK検証(推奨)
すべての公式SDKには、受信したWebhookを安全に検証および解析するための組み込みヘルパーが含まれています。2つのメソッドが利用可能です:unwrap(): Verifies signatures using your webhook secret keyunsafe_unwrap(): Parses payloads without verification
手動検証(代替)
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 Payloadをご覧ください。
Webhookへの応答
- イベントの受領を認識するためにWebhookハンドラは
2xx status codeを返す必要があります。 - その他のレスポンスは失敗と見なされ、Webhookは再試行されます。
ベストプラクティス
Use HTTPS endpoints only
Use HTTPS endpoints only
Webhookエンドポイントには常にHTTPS URLを使用してください。HTTPエンドポイントは中間者攻撃に脆弱で、Webhookデータが漏洩します。
Respond immediately
Respond immediately
Webhookを受信したら即座に
200ステータスコードを返し、イベントの処理は非同期で行ってタイムアウトを回避してください。Handle duplicate events
Handle duplicate events
webhook-idヘッダーを使用して冪等性を実装し、同じイベントを複数回安全に処理できるようにします。Secure your webhook secret
Secure your webhook secret
Webhookシークレットは環境変数やシークレットマネージャーを使って安全に保管してください。シークレットをバージョン管理にコミットしないでください。
Webhookペイロード構造
Webhookペイロード構造を理解することで、イベントを正しく解析し処理できます。リクエスト形式
ヘッダー
このWebhookイベントの一意の識別子です。冪等性チェックに使用してください。
Webhookの真正性を確認するためのHMAC SHA256署名です。
Webhookが送信された時刻のUnixタイムスタンプ(秒単位)です。
リクエストボディ
あなたのDodo Paymentsビジネス識別子です。
この webhook をトリガーしたイベントタイプ(例:
payment.succeeded、subscription.active)。イベントが発生した時刻のISO 8601形式のタイムスタンプです。
イベントに関する詳細情報を含むイベント固有のペイロードです。
例のペイロード
Webhookのテスト
Dodo Paymentsダッシュボードから直接Webhook統合をテストして、エンドポイントが正しく機能していることを確認できます。
テストインターフェースへのアクセス
Webhookをテストする
テストインターフェースは、Webhookエンドポイントをテストするための包括的な方法を提供します:Select Event Type
テストしたい特定のイベントタイプ(例:
payment.succeeded、payment.failedなど)をドロップダウンメニューから選択します。ドロップダウンにはエンドポイントが受信可能なすべてのWebhookイベントタイプが含まれています。
テストの確認
実装例
Webhookの検証と処理を示す完全なExpress.js実装は次のとおりです:Testing Webhooks with the CLI
The Dodo Payments CLI provides two commands for testing webhooks during local development, without needing to leave your terminal.Listen for Live Webhooks Locally
Forward real webhook events from your test mode account to your local development server in real time:http://localhost:3000/webhook), preserving all headers including signature headers for verification testing.
The listener only works with test mode API keys. Run
dodo login and select Test Mode before using this command.Trigger Mock Webhook Events
Send mock webhook payloads to any endpoint without creating real transactions:CLI Webhook Testing Docs
See the full CLI webhook testing documentation
Advanced Settings
The Advanced Settings tab provides additional configuration options for fine-tuning your webhook endpoint behavior.Rate Limiting (Throttling)
Control the rate at which webhook events are delivered to your endpoint to prevent overwhelming your system.Configure Rate Limit
Editボタンをクリックしてレート制限設定を変更します。
デフォルトではWebhookに「No rate limit」が適用され、イベントは発生と同時に配信されます。
Custom Headers
Add custom HTTP headers to all webhook requests sent to your endpoint. This is useful for authentication, routing, or adding metadata to your webhook requests.Transformations
Transformations allow you to modify a webhook’s payload and redirect it to a different URL. This powerful feature enables you to:- Modify the payload structure before processing
- Route webhooks to different endpoints based on content
- Add or remove fields from the payload
- Transform data formats
Configure Transformation
Edit transformationをクリックして変換ルールを定義します。
JavaScriptを使用してWebhookペイロードを変換し、別のターゲットURLを指定できます。
Monitoring Webhook Logs
The Logs tab provides comprehensive visibility into your webhook delivery status, allowing you to monitor, debug, and manage webhook events effectively.
Activity Monitoring
The Activity tab provides real-time insights into your webhook delivery performance with visual analytics.
Email Alerts
Stay informed about your webhook health with automatic email notifications. When webhook deliveries start failing or your endpoint stops responding, you’ll receive email alerts so you can quickly address issues and keep your integrations running smoothly.
Enable Email Alerts
Deploy to Cloud Platforms
Ready to deploy your webhook handler to production? We provide platform-specific guides to help you deploy webhooks to popular cloud providers with best practices for each platform.Vercel
Deploy webhooks to Vercel with serverless functions
Cloudflare Workers
Run webhooks on Cloudflare’s edge network
Supabase Edge Functions
Integrate webhooks with Supabase
Netlify Functions
Deploy webhooks as Netlify serverless functions
各プラットフォームガイドには、環境構築、署名検証、およびそのプロバイダー固有のデプロイ手順が含まれています。
