サブスクリプション コンポーネント
すべての Webhook サブスクリプションは、通知の送信先、セキュリティ保護方法、共有方法を制御するサポートコンポーネントに依存しています。このページでは、各コンポーネントが何をし、いつ使用するかについて説明します。
必須
カテゴリとチャネル/サービス: Select a category (Channels, Numbers and senders, or Tools), then choose a specific channel or service.
Webhook イベント: Which events you want to receive: DELIVERY, INBOUND_MESSAGE, CLICK, and more.
通知プロファイル: Specifies where notifications are sent (webhook URL) and delivery settings. Every subscription must reference one.
オプション
フィルター: Narrow down which events trigger webhooks. See Subscription filters and scope.
認証設定: Define how the system authenticates when sending notifications. Only needed if your webhook requires Basic, HMAC, or OAuth.
証明書: Mutual TLS (mTLS) certificates for enhanced webhook security.
通知プロファイル [#notification-profiles]
通知プロファイルは、イベント通知の送信先と配信方法を定義します。正しく機能するには、すべての Webhook サブスクリプションに有効な通知プロファイルが含まれている必要があります。
通知プロファイルには、次のものが含まれます。
- Webhook URL: 通知を受信するエンドポイント
- 配信設定: バッチサイズと応答の検証
- 認証 (オプション): Webhook 配信のセキュリティ設定
- 証明書 (オプション): トランスポート層セキュリティ用の mTLS 証明書
スタンドアロン通知プロファイル [#standalone-profiles]
スタンドアロン通知プロファイルは独立して動作し、サブスクリプションにはリンクされません。スタンドアロン プロファイルを使用して、Webhook URL が notifyURL や webhookURL などのパラメーターを使用して API リクエストで直接提供された場合の通知動作を一元管理します。
Webhook URL を含む API リクエストを送信すると、システムは一致するスタンドアロン通知プロファイルをチェックします。一致するものが見つかった場合、システムはそのプロファイルで定義されている詳細設定、証明書、またはセキュリティ構成を適用します。一致するプロファイルが存在しない場合、システムは追加の設定なしでイベントを転送します。詳細については、Webhook URL のオーバーライド動作を参照してください。
スタンドアロン プロファイルの種類 [#standalone-types]
| タイプ | 説明 | 制限 | 優先度 |
|---|---|---|---|
| NULL プロファイル | URL のないスタンドアロン プロファイル | アカウントごとに 1 つ | 一致する URL プロファイルがない場合にのみ使用されます |
| URL プロファイル | APIリクエストの notifyURL または webhookURL に一致するURLを持つスタンドアロンプロファイル | アカウントごとに複数 | 一致が見つかったときに NULL プロファイルよりも優先されます |
処理ロジック [#standalone-processing]
API 要求に Webhook URL が含まれ、スタンドアロン通知プロファイルが構成されている場合:
- 完全一致: システムは、URL が完全に一致するプロファイルを検索します
- **フォールバック:**一致するものが見つからない場合は、NULLプロファイルが存在する場合はそれを使用します
- デフォルト: どちらも見つからない場合は、追加の設定なしでイベントを転送します。
例 [#standalone-example]
クライアントは SMS API を使用し、リクエストに Webhook 構成を含めます。
スタンドアロン通知プロファイルを使用: URL https://www.example.com/sms/advanced, のプロファイルが存在する場合、配信レポートの転送時に、そのプロファイルで定義されている詳細設定、セキュリティ構成、または証明書が適用されます。
スタンドアロン通知プロファイルなし: システムは、追加の設定なしで配信レポートを URL に転送します。
もっと詳しく知る通知プロファイルの作成、編集、削除については、「通知プロファイルの管理」を参照してください。
認証設定 [#authentication-settings]
認証設定では、Webhook エンドポイントに通知を送信するときに NTT CPaaS が認証する方法を定義します。これらのセキュリティ設定は、NTT CPaaSのみがシステムに通知を配信できるようにすることで、Webhookを保護します。
認証方法 [#authentication-methods]
基本認証
各 Webhook 要求で送信されるユーザー名とパスワード。資格情報ベースのセキュリティを必要とするほとんどのユースケースに適しています。
HMACの
秘密鍵と HMAC アルゴリズムを使用して Webhook ペイロードに暗号化署名し、通知が NTT CPaaS から発信されたことを確認できます。
OAuth 2.0
OAuth 準拠のシステムとの統合のためのトークンベースの認証。トークン URL、権限タイプ、およびオプションのクライアント資格情報を構成します。
署名と検証をリクエストする [#request-signing]
通知プロファイルでHMAC認証が設定されている場合、NTT CPaaSはWebhookリクエストに署名し、NTT CPaaSから発信されたものであることを確認できます。署名ヘッダーは、そのプロファイルを介して送信される各リクエストに含まれます。
検証プロセス:
- NTT CPaaS アカウント設定から Webhook 署名キーを取得します。
- 受信 Webhook 要求から署名ヘッダーを抽出します。
- 署名キーを使用して、未加工のリクエスト本文のHMAC-SHA256を計算します。JSON 本文全体を受信したとおりに使用します。ハッシュを計算する前に、解析、再フォーマット、空白の削除、または改行文字の削除は行わないでください。変更を加えると、署名が一致しなくなります。
- 計算された署名とヘッダー値を比較します。
- 一致する場合、Webhook は本物です。
正確な署名ヘッダー名は、設定によって異なります。ヘッダー名と署名動作は、NTT CPaaS アカウント設定またはアカウントマネージャーに確認してください。
通知プロファイルには、認証なしまたは有効な認証設定を含める必要があります。空または無効な設定は、Webhook 配信を妨げます。OAuth の場合は、トークン URL がアクセス可能で有効であることを確認します。システムは、Webhook 配信の必要に応じて新しいアクセストークンを要求します。
もっと詳しく知る認証設定の作成、編集、削除は、認証設定の管理を参照してください。
証明書 [#certificates]
証明書は、Webhookエンドポイントの相互TLS(mTLS)を有効にし、安全な通信中にNTT CPaaSとシステムの両方が相互に認証できるようにします。
相互 TLS について [#understanding-mtls]
標準の HTTPS/TLS では、クライアントのみがサーバーを認証します。相互 TLS では、両当事者が相互に認証します。
- サーバー検証: システムがNTT CPaaS証明書を検証します。
- クライアント検証: NTT CPaaS は証明書を検証します。
- 暗号化された接続: 両当事者は、認証が成功した後にのみ安全な接続を確立します。
この双方向認証は、アプリケーションレベルの認証 (Basic、HMAC、OAuth) とは別に、最初の TLS ハンドシェイク中の接続レベルで行われます。
mTLS とサブスクリプションの連携 [#mtls-with-subscriptions]
通知プロファイルで mTLS が有効になっている場合:
- NTT CPaaS はクライアントとして機能します: 接続を開始し、イベント通知を送信します。
- Webhook がサーバーとして機能します: 接続を受信し、NTT CPaaS 証明書を検証します。
- 証明書の交換: データが送信される前に、両当事者が証明書を交換して検証します。
クライアント証明書を NTT CPaaS にアップロードし、通知プロファイルに添付します。イベントがその Webhook に送信されると、接続はアップロードされた証明書を使用します。
相互 TLS は、トランスポート層をセキュリティで保護します。Basic auth、HMAC、または OAuth 2.0 を使用したリクエストレベルの認証については、上記の 認証 settings を参照してください。両方を一緒に使用して、階層化されたセキュリティを実現できます。
もっと詳しく知る証明書のアップロード、管理、削除については、 [証明書の管理] を参照してください。
コンポーネントの関連性 [#how-components-relate]
通知プロファイルとイベント・タイプは、独立したリソースです。サブスクリプションは、選択したイベントを通知プロファイルにバインドし、配信設定を作成します。複数のサブスクリプションが同じ通知プロファイルを参照でき、同じイベントタイプが異なるフィルターを使用して異なるサブスクリプションに表示できます。
削除階層 (他のコンポーネントの削除をブロックするコンポーネント) については、「サブスクリプション階層と削除ルール」を参照してください。
コンポーネントは、複数のコンシューマー間で共有できます。ニーズに応じて、共有設定と独立設定のどちらかを選択します。
共有設定
1 つの通知プロファイルで使用される 1 つの認証設定で、複数のサブスクリプション (SMS、電子メール、WhatsApp) を処理します。1 つのサブスクリプションを削除しても、他のサブスクリプションには影響しません。同じプロファイルと資格情報を引き続き使用します。
独立したセットアップ
サブスクリプションごとに個別の通知プロファイルがあり、それぞれに独自の認証設定があります。完全な分離。1 つのサブスクリプションのプロファイルを削除しても、他のサブスクリプションには影響しません。
どのアプローチがユースケースに適合するかを事前に決定します。共有コンポーネントは構成のオーバーヘッドを削減しますが、削除の依存関係を作成します。独立したコンポーネントは個別に管理するのが簡単ですが、より多くのセットアップが必要です。
通知プロファイルの管理
通知プロファイルを作成、編集、削除します。
認証設定の管理
認証設定を作成、編集、削除します。
証明書の管理
mTLS証明書のアップロード、管理、削除。
サブスクリプションの階層と削除ルール
コンポーネント階層図、削除制約、および削除シーケンス。