メインコンテンツへスキップ
Webhook カバー画像
Webhooksは、Dodo Paymentsアカウントで特定のイベントが発生したときにリアルタイム通知を提供します。Webhooksを使用してワークフローを自動化し、データベースを更新し、通知を送信し、システムを同期させます。
私たちのWebhook実装は、Standard Webhooks仕様に従っており、業界のベストプラクティスおよび既存のWebhookライブラリとの互換性を確保しています。

主な機能

リアルタイム配信

イベントが発生したときに即時通知を受け取ります

デフォルトで安全

HMAC SHA256署名検証が含まれています

自動再試行

指数バックオフを伴う組み込みの再試行ロジック

イベントフィルタリング

必要なイベントのみにサブスクライブします

始めに

1

Webhook設定にアクセスする

DodoPaymentsダッシュボードに移動し、Settings > Webhooksに進みます。
2

Webhookエンドポイントを作成する

Add Webhookをクリックして新しいWebhookエンドポイントを作成します。
Webhookを追加
3

エンドポイントURLを追加する

Webhookイベントを受信したいURLを入力します。
4

受信するイベントを選択する

イベントリストからWebhookエンドポイントがリッスンする特定のイベントを選択します。
選択したイベントのみがエンドポイントにWebhookをトリガーし、不要なトラフィックと処理を回避します。
5

秘密鍵を取得する

設定ページからWebhookのSecret Keyを取得します。これを使用して受信したWebhookの真正性を確認します。
Webhook秘密鍵を安全に保管し、クライアント側のコードや公開リポジトリに公開しないでください。
6

秘密を回転させる(オプション)

必要に応じて、セキュリティを強化するためにWebhook秘密を回転させることができます。Webhook設定で秘密を回転させるボタンをクリックします。
秘密を回転させると、それが失効し新しいものに置き換えられます。古い秘密は次の24時間のみ有効です。その後、古い秘密での検証は失敗します。
現在の秘密が侵害された疑いがある場合は、定期的にまたは直ちに秘密の回転を使用してください。

サブスクライブしたイベントの設定

各Webhookエンドポイントが受信したい特定のイベントを設定できます。

イベント設定へのアクセス

1

Webhookの詳細に移動する

Dodo Paymentsダッシュボードに移動し、Settings > Webhooksに進みます。
2

エンドポイントを選択する

設定したいWebhookエンドポイントをクリックします。
3

イベント設定を開く

Webhookの詳細ページで、「サブスクライブしたイベント」セクションが表示されます。編集ボタンをクリックしてイベントのサブスクリプションを変更します。

イベントサブスクリプションの管理

1

利用可能なイベントを表示する

インターフェースは、階層構造で整理されたすべての利用可能なWebhookイベントを表示します。イベントはカテゴリごとにグループ化されています(例:disputepaymentsubscription)。
2

検索とフィルタリング

検索バーを使用して、イベント名やキーワードを入力して特定のイベントを迅速に見つけます。
3

イベントを選択する

受信したいイベントの隣にあるチェックボックスをオンにします。次のことができます:
  • 個々のサブイベントを選択する(例:dispute.accepteddispute.challenged
  • 親イベントを選択して、関連するすべてのサブイベントを受信する
  • 必要に応じて特定のイベントをミックス&マッチする
4

イベントの詳細を確認する

各イベントの隣にある情報アイコン(ⓘ)にカーソルを合わせると、そのイベントがトリガーされる条件の説明が表示されます。
5

設定を保存する

保存をクリックして変更を適用するか、キャンセルをクリックして変更を破棄します。
すべてのイベントの選択を解除すると、Webhookエンドポイントは通知を受け取らなくなります。アプリケーションが正常に機能するために必要なイベントは少なくとも選択してください。

Webhook配信

タイムアウト

Webhookには、接続および読み取り操作のための15秒のタイムアウトウィンドウがあります。タイムアウトを避けるために、エンドポイントが迅速に応答することを確認してください。
Webhookを非同期に処理し、200ステータスコードで受信を即座に確認し、その後実際の処理をバックグラウンドで行います。

自動再試行

Webhook配信が失敗した場合、Dodo Paymentsはシステムを圧倒しないように指数バックオフで自動的に再試行します。
試行遅延説明
1すぐに最初の再試行はすぐに行われます
25秒短い遅延の後に2回目の試行
35分増加したバックオフで3回目の試行
430分バックオフを続けて4回目の試行
52時間延長された遅延で5回目の試行
65時間より長い遅延で6回目の試行
710時間最大遅延で7回目の試行
810時間最終試行 - 失敗した場合は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ペイロードとタイムスタンプのHMAC SHA256署名を含むwebhook-signatureヘッダーが含まれています。これはあなたの秘密鍵で署名されています。

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仕様に従って署名を自分で検証できます:
  1. webhook-idwebhook-timestamp、正確な生の文字列化されたpayloadをピリオド(.)で区切って連結して署名メッセージを構築します。
  2. ダッシュボードからのWebhook秘密鍵を使用して、その文字列のHMAC SHA256を計算します。
  3. 計算された署名をwebhook-signatureヘッダーと比較します。一致すれば、Webhookは本物です。
私たちはStandard Webhooks仕様に従っています。署名を検証するために彼らのライブラリを使用できます:https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries。イベントペイロード形式については、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-id
string
required
このWebhookイベントの一意の識別子。冪等性チェックに使用します。
webhook-signature
string
required
Webhookの真正性を検証するためのHMAC SHA256署名。
webhook-timestamp
string
required
Webhookが送信されたときのUnixタイムスタンプ(秒単位)。

リクエストボディ

business_id
string
required
あなたのDodo Paymentsビジネス識別子。
type
string
required
このWebhookをトリガーしたイベントタイプ(例:payment.succeededsubscription.created)。
timestamp
string
required
イベントが発生した時刻のISO 8601形式のタイムスタンプ。
data
object
required
イベントに特有のペイロードで、イベントに関する詳細情報を含みます。

例のペイロード

{
  "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統合をテストして、エンドポイントが正しく機能していることを確認できます。
エンドポイントの詳細

テストインターフェースへのアクセス

1

Webhookに移動する

Dodo Paymentsダッシュボードに移動し、Settings > Webhooksに進みます。
2

エンドポイントを選択する

Webhookエンドポイントをクリックして、その詳細ページにアクセスします。
3

テストタブを開く

テストタブをクリックしてWebhookテストインターフェースにアクセスします。

Webhookをテストする

テストインターフェースは、Webhookエンドポイントをテストするための包括的な方法を提供します:
1

イベントタイプを選択する

ドロップダウンメニューを使用して、テストしたい特定のイベントタイプを選択します(例:payment.succeededpayment.failedなど)。
ドロップダウンには、エンドポイントが受信できるすべての利用可能なWebhookイベントタイプが含まれています。
2

スキーマと例を確認する

インターフェースは、選択したイベントタイプのスキーマ(データ構造)と(サンプルペイロード)を表示します。
3

テストイベントを送信する

例を送信ボタンをクリックして、エンドポイントにテストWebhookを送信します。
重要:テストインターフェースを通じて送信された失敗したメッセージは再試行されません。これはテスト目的のみです。

テストの確認

1

エンドポイントを確認する

Webhookエンドポイントのログを監視して、テストイベントが受信されたことを確認します。
2

署名を検証する

テストペイロードで署名検証が正しく機能していることを確認します。
3

レスポンスをテストする

エンドポイントがイベントの受信を確認するために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イベントがエンドポイントに配信されるレートを制御して、システムが圧倒されないようにします。
1

レート制限設定にアクセスする

高度なタブで、「レート制限(スロットリング)」セクションを見つけます。
2

レート制限を設定する

編集ボタンをクリックしてレート制限設定を変更します。
デフォルトでは、Webhookには「レート制限なし」が適用されており、イベントは発生次第配信されます。
3

制限を設定する

Webhook配信の頻度を制御し、システムの過負荷を防ぐために、希望するレート制限を設定します。
Webhookハンドラーがイベントを処理するのに時間が必要な場合や、複数のイベントをまとめて処理したい場合は、レート制限を使用してください。

カスタムヘッダー

すべてのWebhookリクエストにカスタムHTTPヘッダーを追加します。これは、認証、ルーティング、またはWebhookリクエストにメタデータを追加するのに便利です。
1

カスタムヘッダーを追加する

「カスタムヘッダー」セクションで、カスタムヘッダーのキーを入力します。
2

複数のヘッダーを追加する

必要に応じて、**+**ボタンをクリックして追加のカスタムヘッダーを追加します。
3

設定を保存する

あなたのカスタムヘッダーは、このエンドポイントへのすべてのWebhookリクエストに含まれます。

変換

変換を使用すると、Webhookのペイロードを変更し、別のURLにリダイレクトできます。この強力な機能により、次のことが可能になります:
  • 処理前にペイロード構造を変更する
  • コンテンツに基づいてWebhookを異なるエンドポイントにルーティングする
  • ペイロードからフィールドを追加または削除する
  • データ形式を変換する
1

変換を有効にする

有効スイッチを切り替えて、変換機能をアクティブにします。
2

変換を設定する

変換を編集をクリックして、変換ルールを定義します。
JavaScriptを使用してWebhookペイロードを変換し、異なるターゲットURLを指定できます。
3

変換をテストする

テストインターフェースを使用して、変換が正しく機能することを確認します。
変換はWebhook配信パフォーマンスに大きな影響を与える可能性があります。徹底的にテストし、変換ロジックをシンプルかつ効率的に保ってください。
変換は特に次のような場合に便利です:
  • 異なるデータ形式間の変換
  • 特定の基準に基づくイベントのフィルタリング
  • ペイロードに計算されたフィールドを追加
  • イベントを異なるマイクロサービスにルーティング

Webhookログの監視

ログタブは、Webhook配信状況を包括的に可視化し、Webhookイベントを効果的に監視、デバッグ、管理できるようにします。
ログ

アクティビティモニタリング

アクティビティタブは、視覚的な分析を通じてWebhook配信パフォーマンスに関するリアルタイムの洞察を提供します。
アクティビティ

メールアラート

Webhookの健康状態について自動メール通知で情報を得ることができます。Webhook配信が失敗し始めたり、エンドポイントが応答しなくなったりすると、メールアラートが届き、問題に迅速に対処して統合をスムーズに保つことができます。
Webhookアラート設定のメール通知構成を表示

メールアラートを有効にする

1

アラート設定に移動する

Dodo Paymentsダッシュボードに移動し、ダッシュボード → Webhooks → アラートに進みます。
2

メール通知を有効にする

メール通知をオンにして、Webhook配信の問題に関するアラートを受信し始めます。
3

メールアドレスを設定する

Webhookアラートを受信したいメールアドレスを入力します。Webhook設定に関する特定のイベントが発生したときに、このアドレスに通知を送信します。たとえば、統合に影響を与える可能性のある配信問題などです。
Webhook配信の問題を早期にキャッチし、信頼性のある統合を維持するために、メールアラートを有効にしてください。配信が失敗したり、エンドポイントが応答しなくなったりすると通知されます。

クラウドプラットフォームへのデプロイ

Webhookハンドラーを本番環境にデプロイする準備はできましたか?各プラットフォームのベストプラクティスに従って、人気のあるクラウドプロバイダーにWebhookをデプロイするためのプラットフォーム固有のガイドを提供します。
各プラットフォームガイドには、環境設定、署名検証、特定のプロバイダーに固有のデプロイ手順が含まれています。