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

主な機能

Real-time Delivery

イベント発生時に即座に通知を受け取れます

Secure by Default

HMAC SHA256署名の検証を含みます

Automatic Retries

指数バックオフによる組み込みの再試行ロジック

Event Filtering

必要なイベントのみ購読できます

始めに

1

Access Webhook Settings

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

Create Webhook Endpoint

新しいWebhookエンドポイントを作成するには、Add Webhookをクリックします。
Add Webhook
3

Add Endpoint URL

Webhookイベントを受け取るURLを入力します。
4

Select Events to Receive

イベント一覧からWebhookエンドポイントがリッスンする特定のイベントを選択してください。
選択されたイベントのみがWebhookをトリガーし、不必要なトラフィックや処理を回避できます。
5

Get Secret Key

設定ページでWebhookのSecret Keyを取得します。受信Webhookの真正性を検証するために使用します。
Webhookのシークレットキーは安全に保管し、クライアントサイドのコードや公開リポジトリで公開しないでください。
6

Rotate Secret (Optional)

必要に応じてWebhookシークレットをローテーションしてセキュリティを強化できます。Webhook設定のRotate Secretボタンをクリックしてください。
シークレットをローテーションすると期限切れになり、新しいものに置き換えられます。古いシークレットは次の24時間のみ有効です。その後、古いシークレットを使った検証は失敗します。
セキュリティが懸念される場合や定期的にシークレットをローテーションしてください。

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

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

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

1

Navigate to Webhook Details

Dodo Paymentsダッシュボードにアクセスし、Settings > Webhooksへ移動します。
2

Select Your Endpoint

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

Open Event Settings

Webhook詳細ページで「Subscribed events」セクションが表示されます。Editボタンをクリックしてイベント購読を変更します。

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

1

View Available Events

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

Search and Filter

検索バーにイベント名やキーワードを入力して特定のイベントを素早く見つけてください。
3

Select Events

受け取りたいイベントの横のチェックボックスにチェックを入れてください。次の操作が可能です:
  • 個々のサブイベント(例:dispute.accepteddispute.challenged)を選択
  • 親イベントを選択して関連するすべてのサブイベントを受信
  • ニーズに応じて特定のイベントを組み合わせる
4

Review Event Details

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

Save Configuration

Saveをクリックして変更を適用するか、Cancelをクリックして変更を破棄します。
すべてのイベントの選択を解除すると、Webhookエンドポイントは通知を受け取れなくなります。アプリケーションが適切に動作するために必要なイベントを少なくとも1つ選択してください。

Webhook配信

タイムアウト

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

自動再試行

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ダッシュボードを使用して、個別のメッセージを手動で再試行したり、失敗したメッセージを一括で復旧したりできます。

冪等性

Each webhook event includes a unique webhook-id header. Use this identifier to implement idempotency and prevent duplicate processing.
// 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のセキュリティを確保するために、常にペイロードを検証し、HTTPSを使用してください。

署名の検証

Each webhook request includes a webhook-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 key
  • unsafe_unwrap(): Parses payloads without verification
Provide your webhook secret via DODO_PAYMENTS_WEBHOOK_KEY when initializing the Dodo Payments client.
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 Payloadをご覧ください。

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
必須
このWebhookイベントの一意の識別子です。冪等性チェックに使用してください。
webhook-signature
string
必須
Webhookの真正性を確認するためのHMAC SHA256署名です。
webhook-timestamp
string
必須
Webhookが送信された時刻のUnixタイムスタンプ(秒単位)です。

リクエストボディ

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

例のペイロード

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

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

1

Navigate to Webhooks

Dodo Paymentsダッシュボードにアクセスし、Settings > Webhooksへ移動します。
2

Select Your Endpoint

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

Open Testing Tab

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

Webhookをテストする

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

Select Event Type

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

Review Schema and Example

インターフェースには、選択したイベントタイプのSchema(データ構造)とExample(サンプルペイロード)が表示されます。
3

Send Test Event

Send ExampleボタンをクリックしてテストWebhookをエンドポイントに送信します。
重要:テストインターフェースから送信された失敗メッセージは再試行されません。テスト目的のみで使用してください。

テストの確認

1

Check Your Endpoint

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

Verify Signature

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

Test Response

エンドポイントが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.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
本番イベントを処理する前に、ダッシュボードのテストインターフェースでWebhookハンドラを徹底的にテストしてください。これにより問題を早期に特定し修正できます。

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:
dodo wh listen
The CLI opens a WebSocket connection to Dodo Payments and forwards every webhook event to your local endpoint (e.g., 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:
dodo wh trigger
This interactive tool lets you select from all 22 supported event types and sends realistic mock payloads to your endpoint. It loops so you can test multiple events in one session.
Mock webhook payloads from dodo wh trigger are not signed. Use unsafe_unwrap() instead of unwrap() in your webhook handler during testing only.

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.
1

Access Rate Limit Settings

Advancedタブで「Rate Limit (throttling)」セクションを見つけます。
2

Configure Rate Limit

Editボタンをクリックしてレート制限設定を変更します。
デフォルトではWebhookに「No rate limit」が適用され、イベントは発生と同時に配信されます。
3

Set Limits

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

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.
1

Add Custom Header

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

Add Multiple Headers

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

Save Configuration

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

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
1

Enable Transformations

Enabledスイッチをトグルして変換機能を有効にします。
2

Configure Transformation

Edit transformationをクリックして変換ルールを定義します。
JavaScriptを使用してWebhookペイロードを変換し、別のターゲットURLを指定できます。
3

Test Transformation

テストインターフェースを使用して本番環境に移行する前に変換が正しく動作することを検証します。
変換はWebhook配信パフォーマンスに大きな影響を与える可能性があります。十分にテストし、変換ロジックをシンプルかつ効率的に保ってください。
変換は特に以下の用途に役立ちます:
  • 異なるデータ形式への変換
  • 特定の基準に基づくイベントのフィルタリング
  • ペイロードへの計算済みフィールドの追加
  • イベントを異なるマイクロサービスにルーティング

Monitoring Webhook Logs

The Logs tab provides comprehensive visibility into your webhook delivery status, allowing you to monitor, debug, and manage webhook events effectively.
Logs

Activity Monitoring

The Activity tab provides real-time insights into your webhook delivery performance with visual analytics.
Activity

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.
Webhook Alerting Settings showing email notifications configuration

Enable Email Alerts

1

Navigate to Alerting Settings

Dodo Paymentsダッシュボードにアクセスし、Dashboard → Webhooks → Alertingに移動します。
2

Enable Email Notifications

Email notificationsを有効にしてWebhook配信の問題に関するアラートを受信し始めます。
3

Configure Email Address

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

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.
各プラットフォームガイドには、環境構築、署名検証、およびそのプロバイダー固有のデプロイ手順が含まれています。