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

主な機能

Real-time Delivery

イベント発生時に即座に通知を受信

Secure by Default

HMAC SHA256署名の検証に対応

Automatic Retries

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

Event Filtering

必要なイベントのみを購読

はじめに

Dodo Payments の webhooks portal は、ネイティブなダッシュボードエクスペリエンスとして再構築されました。既存のエンドポイント、署名シークレット、signature verification、イベント名、webhook payload は変更されていません。統合作業は必要ありません。
各機能の場所
  • Developer → Webhooks の下EndpointsEvent catalogLogsActivitySettings タブ。
  • 個別のエンドポイント上 — 配信統計、署名シークレット、Replay history を含む Overview タブ、さらに TestingAdvanced タブと一括 replay アクション。
  • メッセージ上Logs タブから開くと、エンドポイントを開かずに各配信試行を個別に replay できます。
1

Access Webhook Settings

Dodo Payments Dashboard に移動し、Developer → Webhooks を開きます。
2

Create Webhook Endpoint

Add endpoint をクリックして、エンドポイント作成用のサイドシートを開きます。
3

Enter Endpoint URL or Choose Integration

webhook event を受信する URL を入力するか、integration connector を選択して、イベントをサードパーティサービス(Slack、Discord、Zapier、Resend など)へルーティングします。
4

Select Events to Receive

エンドポイントが listen する特定のイベントを選択します。イベントは、リソースごとにグループ化された検索可能なツリーに整理されています。個別のイベントを選択することも、親リソースを選択して関連するすべてのイベントを受信することもできます。
選択したイベントだけがエンドポイントへの webhooks をトリガーするため、不要なトラフィックや処理を避けられます。
5

Create Endpoint

Create endpoint をクリックして設定を保存します。
6

Get Secret Key

webhook signing secret は、エンドポイントの Overview タブに表示されます。受信した webhooks の真正性を検証するために使用します。
webhook secret key は安全に管理し、クライアント側のコードや公開リポジトリに決して公開しないでください。
7

Rotate Secret (Optional)

必要に応じて、セキュリティを強化するために webhook secret をローテーションできます。Overview タブで secret の横にある Rotate secret をクリックします。
secret をローテーションすると、現在の secret は失効し、新しい secret に置き換えられます。古い secret はその後 24 時間のみ有効です。それ以降、古い secret で検証しようとすると失敗します。
定期的に、または現在の secret が漏えいした疑いがある場合は直ちに secret rotation を実行してください。

Integration Connectors

独自の webhook receiver を構築する代わりに、integration connector を使用して webhook event をサードパーティサービスへ直接ルーティングできます。これにより、一般的なプラットフォーム向けにカスタム webhook handler を記述・保守する必要がなくなります。

Connector の仕組み

connector は、Dodo Payments event を送信先が想定する形式に変換する処理を実行します。入力する詳細は送信先によって異なります。 ダッシュボードの connector picker には、現在ビジネスで利用できるすべての connector が表示されます。そのため、上の表は網羅的な一覧ではなく、手順付きのセットアップ説明がある送信先として扱ってください。各送信先で event を受信した後にできることについては、External Integrations を参照してください。

Connector の設定

エンドポイントの作成または編集時に connector を選択すると、サイドシートに送信先に合わせたセットアップ手順が表示されます。たとえば、Slack で incoming webhook URL を作成する方法や、Resend API key の確認場所などです。保存する前に connector transformation test を実行し、event が送信先向けに正しく変換されることを確認してください。
コードを書かずにサポート対象の送信先へ接続するには connector を使用します。カスタムロジックが必要な場合は、代わりに transformation を使用した標準エンドポイントを使ってください。

Subscribed Events の設定

各 webhook endpoint が受信する特定のイベントを設定できます。
1

Navigate to Webhook Endpoints

Dodo Payments Dashboard に移動し、Developer → Webhooks を開きます。
2

Select Your Endpoint

設定する webhook endpoint をクリックします。
3

Open Event Configuration

Edit をクリックして、エンドポイント設定用のサイドシートを開きます。
4

Browse Event Types

イベントタイプセレクターには、利用可能なすべての webhook event がリソースごとにグループ化された検索可能なツリーで表示されます(例: paymentsubscriptiondispute)。検索バーを使用すると、名前やキーワードから特定のイベントをすばやく見つけられます。
5

Select Events

受信するイベントの横にあるチェックボックスをオンにします。次の操作ができます。
  • 個別のイベントを選択する(例: payment.succeededpayment.failed
  • 親リソースを選択して関連するすべてのイベントを受信する
  • 必要に応じて特定のイベントを組み合わせる
6

Save Configuration

Save をクリックして変更を適用するか、Cancel をクリックして変更を破棄します。
すべてのイベントの選択を解除すると、webhook endpoint は通知を一切受信しなくなります。アプリケーションの正常な動作に必要なイベントを少なくとも選択してください。

Event Catalog

Developer → Webhooks に移動し、Event catalog タブを開きます。ここには Dodo Payments が送信できるすべてのイベントタイプが一覧表示されるため、エンドポイントを購読する前に利用可能なイベントを確認できます。イベントを選択すると、その schema とサンプル payload を表示できます。読み取る予定のフィールドの形式を確認する最も簡単な方法です。

Webhook Events Guide

同じイベントを、リソースごとにグループ化されたリファレンスドキュメントとして参照できます。

Webhook Delivery

タイムアウト

webhooks には、接続操作と読み取り操作の両方に 15 秒のタイムアウトウィンドウ があります。タイムアウトを避けるため、エンドポイントがすぐに応答するようにしてください。
webhooks は非同期で処理し、まず 200 status code を直ちに返して受信を確認した後、実際の処理をバックグラウンドで行ってください。

自動リトライ

webhook delivery が失敗すると、Dodo Payments は指数バックオフで自動的にリトライし、システムに過剰な負荷がかからないようにします。
webhook event ごとのリトライは 最大 8 回 です。たとえば、webhook が成功するまでに 3 回失敗した場合、最初の試行からの合計配信時間は約 35 分 5 秒です。
Dodo Payments dashboard を使用すると、個別のメッセージを手動でリトライしたり、失敗したすべてのメッセージを一括でいつでも復旧したりできます。

Idempotency

各 webhook event には一意の webhook-id header が含まれます。この識別子を使用して idempotency を実装し、重複処理を防止してください。
必ず idempotency checks を実装してください。リトライにより、同じ event を複数回受信する可能性があります。

イベント順序

リトライやネットワーク状況により、webhook event が順不同で届く場合があります。どの順序のイベントにも対応できるようにシステムを設計してください。
webhook event が最初に発生した時点に関係なく、配信時点での最新の payload を受信します。

Webhooks のセキュリティ保護

webhooks のセキュリティを確保するため、常に payload を検証し、HTTPS を使用してください。

署名の検証

各 webhook request には webhook-signature header が含まれます。これは webhook payload と timestamp の HMAC SHA256 signature で、secret key によって署名されています。

SDK verification(推奨)

すべての公式 SDK には、受信した webhooks を安全に検証・解析するための built-in helper が含まれています。利用できる方法は 2 つです。
  • unwrap(): webhook secret key を使用して signature を検証します
  • unsafe_unwrap(): verification なしで payload を解析します
Dodo Payments client の初期化時に、DODO_PAYMENTS_WEBHOOK_KEY を使用して webhook secret を指定します。

Manual verification(代替方法)

SDK を使用していない場合は、Standard Webhooks spec に従って自分で signature を検証できます。
  1. webhook-idwebhook-timestamp、正確な raw stringified payload をピリオド(.)で区切って連結し、署名対象メッセージを作成します。
  2. Dashboard の webhook secret key を使用して、その文字列の HMAC SHA256 を計算します。
  3. 計算した signature と webhook-signature header を比較します。一致すれば webhook は authentic です。
Standard Webhooks specification に従っています。signature の検証には、https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries の libraries を使用できます。event payload formats については、Webhook Payload を参照してください。

ソース IP アドレス

Webhook を認証するために推奨されている方法は、署名検証です。これにより、リクエストが webhook secret を使って署名されたことを証明できますが、ネットワークレベルのチェックではそれを確認できません。 Webhook の配信は、当社の配信インフラストラクチャに属するソース IP アドレスのプールから送信されます。このプールは随時変更されるため、アドレスは統合の固定された特性ではなく、運用上の詳細として扱ってください。
認証メカニズムとしてソース IP allowlist を使用しないでください。allowlist で確認できるのはリクエストの送信元だけであり、それが正規のものか、変更されていないかは確認できません。Verifying Signatures の説明に従い、すべてのリクエストで webhook-signature header を検証してください。
ファイアウォールの背後にインフラストラクチャがあり、明示的な allowlist が必要な場合は、次の点に注意してください。
  • アドレスを恒久的にハードコードしないでください。 範囲は時間の経過とともに追加・廃止されるため、古いルールによって配信が気付かないうちにブロックされます。
  • ファイアウォールを制限する前に、support@dodopayments.com から現在の範囲をリクエストしてください。最新のリストに基づいて作業できます。
  • 変更通知を確認してください。 配信アドレスが変更される場合、影響を受ける Merchant にはメールで通知します。配信の欠落を避けるため、指定された日付までに更新を適用してください。
  • 追加するネットワークルールにかかわらず、署名検証を有効にしておいてください
Serverless および managed hosting platform では、受信 IP フィルタリングを利用できないか、維持することが現実的でない場合がよくあります。これらの環境で適切な制御となるのは署名検証であり、allowlist は必要ありません。
ブロックされた配信は、その他の失敗と同様に扱われ、Automatic Retries に記載されたスケジュールで再試行されます。ファイアウォールルールが原因で配信に失敗した場合は、ルールを修正した後で再送信できます。詳しくは Replaying and Recovering Messages を参照してください。

Webhook への応答

  • webhook handler は、イベントを受信したことを確認するために 2xx status code を返す必要があります。
  • その他のレスポンスは失敗として扱われ、webhook は再試行されます。

ベストプラクティス

webhook endpoint には常に HTTPS URL を使用してください。HTTP endpoint は man-in-the-middle 攻撃に対して脆弱であり、webhook データが公開される可能性があります。
webhook を受信したら、直ちに 200 status code を返してください。タイムアウトを避けるため、イベントは非同期で処理します。
webhook-id header を使用して idempotency を実装し、副作用なしに同じイベントを複数回安全に処理できるようにしてください。
webhook secret は、environment variables または secrets manager を使用して安全に保存してください。secret を version control にコミットしないでください。

Webhook Payload の構造

Webhook payload の構造を理解すると、イベントを正しく解析・処理できます。

リクエスト形式

Headers

string
必須
この webhook event の一意の識別子。idempotency チェックに使用します。
string
必須
webhook の信頼性を検証するための HMAC SHA256 signature。
string
必須
webhook が送信された時刻を表す Unix timestamp(秒単位)。

Request Body

string
必須
Dodo Payments のビジネス識別子。
string
必須
この webhook を発生させたイベントタイプ(例:payment.succeededsubscription.active)。
string
必須
イベントが発生した時刻を ISO 8601 形式で表した timestamp。
object
必須
イベントに関する詳細情報を含む、イベント固有の payload。

Payload の例

Event Types

利用可能なすべての webhook event type を参照

Event Payloads

各イベントの詳細な payload schema を確認

Handle Payment Failures

payment.failed に反応し、declined payment を回復

Webhook のテスト

本番稼働前に endpoint が正しく動作することを確認するため、Dodo Payments dashboard から webhook 統合を直接テストできます。
1

Navigate to Webhooks

Dodo Payments Dashboard に移動し、Developer → Webhooks を開きます。
2

Select Your Endpoint

webhook endpoint をクリックして詳細ページを開きます。
3

Open Testing Tab

Testing tab をクリックして webhook testing interface を開きます。

Example Event の送信

Testing tab はこの endpoint にサンプル payload を送信するため、receiver を検証できます。
1

Select Event Type

Select an event type を使用してテストするイベントを選択します。例:payment.succeeded または payment.failed
2

Send Example

Send example をクリックします。サンプル payload は実際のイベントと同じように、同じ方法で署名されて endpoint URL に配信されます。
Testing tab から送信された失敗メッセージは再試行されません。receiver の検証に使用し、再試行スケジュールのテストには使用しないでください。
3

Check Your Endpoint

tab には Last example sent が送信された時刻が記録されます。イベントが到着したこと、署名検証に成功したこと、2xx status code を返したことを確認してください。

実装例

webhook の検証と処理を示す、完全な Express.js 実装を次に示します。
production event を処理する前に、dashboard testing interface を使用して webhook handler を十分にテストしてください。これにより、問題を早期に特定して修正できます。

CLI を使用した Webhook のテスト

Dodo Payments CLI には、terminal を離れることなく local development 中に webhook をテストできる 2 つのコマンドがあります。

Live Webhook をローカルでリッスンする

test mode account から実際の webhook event を local development server にリアルタイムで転送します。
CLI は Dodo Payments への WebSocket 接続を開き、すべての webhook event をローカル endpoint(例:http://localhost:3000/webhook)に転送します。検証テスト用の signature headers を含む、すべての headers が保持されます。
listener は test mode API keys でのみ動作します。このコマンドを使用する前に dodo login を実行し、Test Mode を選択してください。

Mock Webhook Event をトリガーする

実際の transaction を作成せずに、任意の endpoint へ mock webhook payload を送信します。
この interactive tool ではイベントタイプを選択し、現実的な mock payload を endpoint に送信できます。ループするため、1 回の session で複数のイベントをテストできます。 trigger command は、Dodo Payments が配信する全 47 種類の event type に対応しています。subscription、payment、refund、dispute、license key、payout、credit、abandoned checkout、dunning、entitlement grant の各ファミリーが含まれます。正確なリストについては Supported Webhook Events を参照してください。
dodo wh trigger からの mock webhook payload には署名がありません。テスト中の webhook handler では、unwrap() の代わりに unsafe_unwrap() を使用してください。

CLI Webhook Testing Docs

CLI webhook testing documentation の全文を参照

Advanced Settings

Advanced tab には、webhook endpoint の動作を細かく調整するための追加設定オプションがあります。

Rate Limiting(Throttling)

システムへの過負荷を防ぐため、webhook event が endpoint に配信される速度を制御します。
1

Open Advanced Tab

endpoint details page で Advanced tab をクリックします。
2

Configure Rate Limit

“Rate Limit (throttling)” セクションで Edit をクリックし、rate limit settings を変更します。
デフォルトでは webhook に rate limit は適用されないため、イベントは発生するとすぐに配信されます。
3

Set Your Limit

希望する rate limit を設定し、webhook の配信頻度を制御してシステムの過負荷を防ぎます。
webhook handler でイベントの処理に時間が必要な場合や、複数のイベントをまとめて処理したい場合に rate limiting を使用します。

Custom Headers

endpoint に送信するすべての webhook request に custom HTTP headers を追加します。認証、routing、または metadata の追加に便利です。
1

Add Headers

“Custom Headers” セクションで、各 custom header の KeyValue を入力します。
2

Add Multiple Headers

必要に応じて + ボタンをクリックし、custom header を追加します。
custom headers は、この endpoint へのすべての webhook request に含まれます。

Transformations

Transformations を使用すると、webhook の payload を変更し、必要に応じて別の URL にリダイレクトできます。この強力な機能により、次のことが可能になります。
  • 処理前に payload の構造を変更する
  • 内容に基づいて webhook を異なる endpoint に routing する
  • payload のフィールドを追加または削除する
  • data format を変換する
1

Enable Transformations

Enabled switch をオンにして transformation feature を有効化します。
2

Configure Transformation

Edit transformation をクリックし、JavaScript を使用して transformation rules を定義します。
3

Test Transformation

transformation test interface を使用して、本番稼働前に transformation が正しく動作することを確認します。
Transformations は webhook delivery performance に影響を与える可能性があります。十分にテストし、transformation logic はシンプルかつ効率的に保ってください。
Transformations は特に次の用途に便利です。
  • 異なる data format 間で変換する
  • 特定の条件に基づいてイベントを filtering する
  • payload に計算フィールドを追加する
  • イベントを異なる microservices に routing する

Webhook Logs の監視

Logs tab では webhook delivery status を包括的に確認でき、webhook event を効果的に監視、デバッグ、管理できます。
1

Navigate to Logs Tab

Developer → Webhooks に移動し、Logs tab を開きます。
2

Browse Delivery History

Event type、Message ID、Event ID、Sent at、Attempted at、Response code、Duration の各列を含む、すべての webhook delivery attempt のテーブルを確認できます。
3

Search and Filter

search bar を使用して、ID または event type で特定の message を検索します。status(Succeeded、Failed、Pending など)で filtering し、調査が必要なイベントに絞り込めます。
4

View Message Details

任意の message をクリックして message detail page を開くと、次の情報が表示されます。
  • 完全な webhook payload
  • response code と duration を含むすべての delivery attempt
  • 各 attempt の timestamp
  • endpoint から返されたエラーメッセージ
各 attempt には Replay action があり、ページを離れずにその message だけを再配信できます。

Activity Monitoring

Developer → Webhooks に移動し、Activity tab を開くと、各 endpoint の delivery performance を確認できます。 Delivery activity では、期間に応じて Attempts per 5 minutesAttempts per hour、または Attempts per day として分類された attempt の推移を表示します。各バーは結果別に分割され、セグメントにカーソルを合わせると status、attempt 数、全体に占める割合が表示されます。endpoint の Overview tab にある Delivery stats (last 24h) では、過去 1 日分の同じ情報をまとめて確認できます。
Endpoints tab の Error rate (24h) 列を見ると、endpoint を開く前に対応が必要な endpoint をすぐに把握できます。

Message の再生と復旧

message を再配信する方法は、必要な数によって異なります。
  • 1 件の messageLogs tab から message を開き、attempt の Replay action を使用します。endpoint を開く必要はありません。
  • 複数の message の範囲 — bulk mode は一度に 1 つの endpoint に対して実行されるため、endpoint を開きます。

Bulk での再生

Developer → Webhooks から endpoint を開きます。3 つの mode が利用でき、それぞれその endpoint だけに対して実行されます。設定する範囲は mode によって異なります。
1

Open More Actions

endpoint で More actions を開き、上記 3 つの mode のいずれかを選択します。
2

Set the Range

table に記載されている、その mode が求める範囲を入力します。
3

Start the Run

選択した mode に応じて Recover または Replay をクリックします。
各実行は endpoint の Overview tab にある Replay history に表示され、mode、時間範囲、status、再送信された message 数を確認できます。

Email Alerts

endpoint への webhook delivery が失敗しているときに email notification を受け取り、問題が backlog になる前に対処できるようにします。
1

Navigate to Settings Tab

Developer → Webhooks に移動し、Settings tab を開きます。
2

Find Email Alerting

Email alerting card を見つけます。
3

Configure Email Addresses

alert を受け取るアドレスを入力します。複数のアドレスはカンマで区切り、alert を無効にする場合はフィールドを空にします。
4

Save

Save をクリックして変更を適用します。
email alert を有効にして webhook delivery の問題を早期に検知し、信頼性の高い統合を維持してください。

Cloud Platform へのデプロイ

webhook handler を本番環境にデプロイする準備はできましたか?各 platform に適したベストプラクティスを用いて、一般的な cloud provider に webhook をデプロイできる platform-specific guide を提供しています。

Vercel

serverless functions を使用して Vercel に webhook をデプロイ

Cloudflare Workers

Cloudflare の edge network で webhook を実行

Supabase Edge Functions

webhook を Supabase と統合

Netlify Functions

webhook を Netlify serverless functions としてデプロイ
各 platform guide には、その provider に固有の environment setup、署名検証、deployment steps が含まれています。

関連する API Reference

Create Webhook

webhook endpoint をプログラムで作成・設定するための API reference

List Webhooks

webhook endpoint を取得・管理するための API reference
最終更新日 2026年8月21日