Webhooksは、Dodo Paymentsアカウントで特定のイベントが発生したときにリアルタイム通知を提供します。Webhooksを使用してワークフローを自動化し、データベースを更新し、通知を送信し、システムを同期させます。
私たちのWebhook実装は、Standard Webhooks仕様に従っており、業界のベストプラクティスおよび既存のWebhookライブラリとの互換性を確保しています。
主な機能
リアルタイム配信
イベントが発生したときに即時通知を受け取ります
デフォルトで安全
HMAC SHA256署名検証が含まれています
自動再試行
指数バックオフを伴う組み込みの再試行ロジック
イベントフィルタリング
必要なイベントのみにサブスクライブします
始めに
Webhook設定にアクセスする
DodoPaymentsダッシュボードに移動し、Settings > Webhooksに進みます。
Webhookエンドポイントを作成する
Add Webhookをクリックして、新しいWebhookエンドポイントを作成します。エンドポイントURLを追加する
Webhookイベントを受信したいURLを入力します。
受信するイベントを選択する
イベントリストからWebhookエンドポイントがリッスンする特定のイベントを選択します。選択したイベントのみがエンドポイントにWebhookをトリガーし、不要なトラフィックと処理を回避します。
シークレットキーを取得する
設定ページからWebhookのSecret Keyを取得します。これを使用して、受信したWebhookの真正性を確認します。Webhookのシークレットキーを安全に保管し、クライアント側のコードや公開リポジトリに露出しないでください。
秘密を回転させる(オプション)
必要に応じて、セキュリティを強化するためにWebhook秘密を回転させることができます。Webhook設定で秘密を回転させるボタンをクリックします。秘密を回転させると、それが失効し、新しいものに置き換えられます。古い秘密は次の24時間のみ有効です。その後、古い秘密での検証は失敗します。
現在の秘密が侵害された疑いがある場合は、定期的にまたは直ちに秘密の回転を使用してください。
サブスクライブしたイベントの設定
各Webhookエンドポイントが受信したい特定のイベントを設定できます。
イベント設定へのアクセス
Webhookの詳細に移動する
Dodo Paymentsダッシュボードに移動し、Settings > Webhooksに進みます。
エンドポイントを選択する
設定したいWebhookエンドポイントをクリックします。
イベント設定を開く
Webhookの詳細ページで、「サブスクライブしたイベント」セクションが表示されます。編集ボタンをクリックしてイベントのサブスクリプションを変更します。
イベントサブスクリプションの管理
利用可能なイベントを表示する
インターフェースは、階層構造で整理されたすべての利用可能なWebhookイベントを表示します。イベントはカテゴリごとにグループ化されています(例: dispute, payment, subscription)。
検索とフィルタリング
検索バーを使用して、イベント名やキーワードを入力して特定のイベントを迅速に見つけます。
イベントを選択する
受信したいイベントの横にあるチェックボックスをチェックします。次のことができます:
- 個別のサブイベントを選択する(例:
dispute.accepted, dispute.challenged)
- 親イベントを選択して、関連するすべてのサブイベントを受信する
- 必要に応じて特定のイベントを組み合わせて選択する
イベントの詳細を確認する
各イベントの隣にある情報アイコン(ⓘ)にカーソルを合わせると、そのイベントがトリガーされる条件の説明が表示されます。
設定を保存する
保存をクリックして変更を適用するか、キャンセルをクリックして変更を破棄します。
すべてのイベントの選択を解除すると、Webhookエンドポイントは通知を受け取らなくなります。アプリケーションが正常に機能するために必要なイベントは少なくとも選択してください。
Webhook配信
タイムアウト
Webhookには、接続および読み取り操作のための15秒のタイムアウトウィンドウがあります。タイムアウトを避けるために、エンドポイントが迅速に応答することを確認してください。
Webhookを非同期に処理するには、受信を即座に確認し、200ステータスコードを返し、その後、実際の処理をバックグラウンドで行います。
自動再試行
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秒です。
Dodo Paymentsダッシュボードを使用して、個々のメッセージを手動で再試行したり、失敗したすべてのメッセージを一括回復したりできます。
冪等性
各Webhookイベントには、ユニークなwebhook-idヘッダーが含まれています。この識別子を使用して、冪等性を実装し、重複処理を防ぎます。
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();
app.post('/webhook', (req, res) => {
const webhookId = req.headers['webhook-id'];
if (processedWebhooks.has(webhookId)) {
return res.status(200).json({ received: true });
}
processedWebhooks.add(webhookId);
// Process the webhook...
});
常に冪等性チェックを実装してください。再試行のため、同じイベントを複数回受信する可能性があります。
イベントの順序
Webhookイベントは、再試行やネットワーク条件により順不同で到着する場合があります。システムを設計して、任意の順序でイベントを処理できるようにしてください。
Webhookイベントが元々発生した時期に関係なく、配信時の最新のペイロードを受け取ります。
Webhookのセキュリティ
Webhookのセキュリティを確保するために、常にペイロードを検証し、HTTPSを使用してください。
署名の検証
各Webhookリクエストには、webhook-signatureヘッダー、WebhookペイロードとタイムスタンプのHMAC SHA256署名が含まれ、あなたのシークレットキーで署名されています。
SDK検証(推奨)
すべての公式SDKには、受信したWebhookを安全に検証および解析するための組み込みヘルパーが含まれています。2つのメソッドが利用可能です:
unwrap(): Webhookシークレットキーを使用して署名を検証します
unsafe_unwrap(): 検証なしでペイロードを解析します
Dodo Paymentsクライアントを初期化する際に、DODO_PAYMENTS_WEBHOOK_KEYを介してWebhookシークレットを提供してください。
import DodoPayments from 'dodopayments';
import express from 'express';
const app = express();
app.use(express.raw({ type: 'application/json' }));
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});
app.post('/webhook', async (req, res) => {
try {
const unwrapped = client.webhooks.unwrap(req.body.toString(), {
headers: {
'webhook-id': req.headers['webhook-id'] as string,
'webhook-signature': req.headers['webhook-signature'] as string,
'webhook-timestamp': req.headers['webhook-timestamp'] as string,
},
});
res.json({ received: true });
} catch (error) {
res.status(401).json({ error: 'Invalid signature' });
}
});
手動検証(代替)
SDKを使用していない場合は、Standard Webhooks仕様に従って署名を自分で検証できます:
webhook-id、webhook-timestamp、及び正確な生の文字列化されたpayloadを、ピリオド(.)で区切って連結して署名メッセージを構築します。
- ダッシュボードからのWebhookシークレットキーを使用して、その文字列のHMAC SHA256を計算します。
- 計算された署名を
webhook-signatureヘッダーと比較します。一致すれば、Webhookは真正です。
Webhookへの応答
- Webhookハンドラーは、イベントの受信を確認するために
2xx status codeを返す必要があります。
- その他の応答は失敗と見なされ、Webhookは再試行されます。
ベストプラクティス
Webhookエンドポイントには常にHTTPS URLを使用してください。HTTPエンドポイントは中間者攻撃に対して脆弱であり、Webhookデータを公開します。
Webhookを受信した際に、即座に200ステータスコードを返します。タイムアウトを避けるために、イベントを非同期に処理します。app.post('/webhook', async (req, res) => {
// Acknowledge receipt immediately
res.status(200).json({ received: true });
// Process asynchronously
processWebhookAsync(req.body).catch(console.error);
});
webhook-idヘッダーを使用して冪等性を実装し、同じイベントを副作用なしで安全に複数回処理します。
環境変数やシークレットマネージャーを使用してWebhook秘密を安全に保管します。決してシークレットをバージョン管理にコミットしないでください。
Webhookペイロード構造
Webhookペイロード構造を理解することで、イベントを正しく解析し処理できます。
リクエスト形式
POST /your-webhook-url
Content-Type: application/json
ヘッダー
このWebhookイベントの一意の識別子。冪等性チェックに使用します。
Webhookの真正性を検証するためのHMAC SHA256署名。
Webhookが送信されたときのUnixタイムスタンプ(秒単位)。
リクエストボディ
あなたのDodo Paymentsビジネス識別子。
このWebhookをトリガーしたイベントタイプ(例: payment.succeeded, subscription.created)。
イベントが発生した時刻のISO 8601形式のタイムスタンプ。
イベントに特有のペイロードで、イベントに関する詳細情報を含みます。
リソースのタイプ: Payment, Subscription, Refund, Dispute、またはLicenseKey。
追加フィールドはイベントタイプによって異なります。完全なスキーマについては、イベント固有のドキュメントを参照してください。
例のペイロード
{
"business_id": "string",
"type": "payment.succeeded | payment.failed |...",
"timestamp": "2024-01-01T12:00:00Z",
"data": {
"payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
// ... event-specific fields (see below)
}
}
Webhookのテスト
Dodo Paymentsダッシュボードから直接Webhook統合をテストして、エンドポイントが正しく機能していることを確認できます。
テストインターフェースへのアクセス
Webhookに移動する
Dodo Paymentsダッシュボードに移動し、Settings > Webhooksに進みます。
エンドポイントを選択する
Webhookエンドポイントをクリックして、その詳細ページにアクセスします。
テストタブを開く
テストタブをクリックしてWebhookテストインターフェースにアクセスします。
Webhookをテストする
テストインターフェースは、Webhookエンドポイントをテストするための包括的な方法を提供します:
イベントタイプを選択する
ドロップダウンメニューを使用して、テストしたい特定のイベントタイプを選択します(例: payment.succeeded, payment.failedなど)。ドロップダウンには、あなたのエンドポイントが受信できるすべての利用可能なWebhookイベントタイプが含まれています。
スキーマと例を確認する
インターフェースは、選択したイベントタイプのスキーマ(データ構造)と例(サンプルペイロード)を表示します。
テストイベントを送信する
例を送信ボタンをクリックして、エンドポイントにテストWebhookを送信します。重要:テストインターフェースを通じて送信された失敗したメッセージは再試行されません。これはテスト目的のみです。
テストの確認
エンドポイントを確認する
Webhookエンドポイントのログを監視して、テストイベントが受信されたことを確認します。
署名を検証する
テストペイロードで署名検証が正しく機能していることを確認します。
レスポンスをテストする
あなたのエンドポイントが受信を確認するために2xxステータスコードを返すことを確認します。
実装例
Webhookの検証と処理を示す完全なExpress.js実装は次のとおりです:
import { Webhook } from "standardwebhooks";
import express from "express";
const app = express();
app.use(express.json());
const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);
app.post('/webhook/dodo-payments', async (req, res) => {
try {
// Extract webhook headers
const webhookHeaders = {
"webhook-id": req.headers["webhook-id"] as string,
"webhook-signature": req.headers["webhook-signature"] as string,
"webhook-timestamp": req.headers["webhook-timestamp"] as string,
};
// Verify the webhook signature
const payload = JSON.stringify(req.body);
await webhook.verify(payload, webhookHeaders);
// Acknowledge receipt immediately
res.status(200).json({ received: true });
// Process webhook asynchronously
processWebhookAsync(req.body).catch(console.error);
} catch (error) {
console.error('Webhook verification failed:', error);
res.status(400).json({ error: 'Invalid signature' });
}
});
async function processWebhookAsync(data: any) {
// Handle the webhook event based on type
switch (data.type) {
case 'payment.succeeded':
await handlePaymentSucceeded(data);
break;
case 'subscription.created':
await handleSubscriptionCreated(data);
break;
// Add more event handlers...
}
}
Webhookハンドラーを本番イベントを処理する前に、ダッシュボードのテストインターフェースを使用して徹底的にテストしてください。これにより、問題を早期に特定して修正できます。
高度な設定
高度な設定タブでは、Webhookエンドポイントの動作を微調整するための追加の構成オプションを提供します。
レート制限(スロットリング)
Webhookイベントがエンドポイントに配信されるレートを制御して、システムが圧倒されないようにします。
レート制限設定にアクセスする
高度なタブで、「レート制限(スロットリング)」セクションを見つけます。
レート制限を設定する
編集ボタンをクリックしてレート制限設定を変更します。デフォルトでは、Webhookには「レート制限なし」が適用されており、イベントは発生次第配信されます。
制限を設定する
Webhook配信の頻度を制御し、システムの過負荷を防ぐために、希望するレート制限を設定します。
Webhookハンドラーがイベントを処理するのに時間が必要な場合や、複数のイベントをまとめて処理したい場合は、レート制限を使用してください。
カスタムヘッダー
すべてのWebhookリクエストにカスタムHTTPヘッダーを追加します。これは、認証、ルーティング、またはWebhookリクエストにメタデータを追加するのに便利です。
カスタムヘッダーを追加する
「カスタムヘッダー」セクションで、カスタムヘッダーのキーと値を入力します。
複数のヘッダーを追加する
必要に応じて、**+**ボタンをクリックして追加のカスタムヘッダーを追加します。
設定を保存する
あなたのカスタムヘッダーは、このエンドポイントへのすべてのWebhookリクエストに含まれます。
変換を使用すると、Webhookのペイロードを変更し、別のURLにリダイレクトできます。この強力な機能により、次のことが可能になります:
- 処理前にペイロード構造を変更する
- コンテンツに基づいてWebhookを異なるエンドポイントにルーティングする
- ペイロードからフィールドを追加または削除する
- データ形式を変換する
変換を有効にする
有効スイッチを切り替えて、変換機能をアクティブにします。
変換を設定する
変換を編集をクリックして、変換ルールを定義します。JavaScriptを使用してWebhookペイロードを変換し、異なるターゲットURLを指定できます。
変換をテストする
テストインターフェースを使用して、変換が正しく機能することを確認します。
変換はWebhook配信パフォーマンスに大きな影響を与える可能性があります。徹底的にテストし、変換ロジックをシンプルかつ効率的に保ってください。
変換は特に次のような場合に便利です:
- 異なるデータ形式間の変換
- 特定の基準に基づくイベントのフィルタリング
- ペイロードに計算されたフィールドを追加
- イベントを異なるマイクロサービスにルーティング
Webhookログの監視
ログタブは、Webhook配信状況を包括的に可視化し、Webhookイベントを効果的に監視、デバッグ、管理できるようにします。
アクティビティモニタリング
アクティビティタブは、視覚的な分析を通じてWebhook配信パフォーマンスに関するリアルタイムの洞察を提供します。
メールアラート
Webhookの健康状態について自動メール通知で情報を得ることができます。Webhook配信が失敗し始めたり、エンドポイントが応答しなくなったりすると、メールアラートが届き、問題に迅速に対処して統合をスムーズに保つことができます。
メールアラートを有効にする
アラート設定に移動する
Dodo Paymentsダッシュボードに移動し、ダッシュボード → Webhooks → アラートに進みます。
メール通知を有効にする
メール通知をオンにして、Webhook配信の問題に関するアラートを受信し始めます。
メールアドレスを設定する
Webhookアラートを受信したいメールアドレスを入力します。Webhook設定に関する特定のイベントが発生したときに、このアドレスに通知を送信します。たとえば、統合に影響を与える可能性のある配信問題などです。
Webhook配信の問題を早期にキャッチし、信頼性のある統合を維持するために、メールアラートを有効にしてください。配信が失敗したり、エンドポイントが応答しなくなったりすると通知されます。
クラウドプラットフォームへのデプロイ
Webhookハンドラーを本番環境にデプロイする準備はできましたか?各プラットフォームのベストプラクティスに従って、人気のあるクラウドプロバイダーにWebhookをデプロイするためのプラットフォーム固有のガイドを提供します。
各プラットフォームガイドには、環境設定、署名検証、特定のプロバイダーに固有のデプロイ手順が含まれています。