Webhook サブスクリプションの管理

Webhook サブスクリプションは、通知をトリガーするイベントと、それらの通知をシステムに配信する方法を定義します。サブスクリプションの作成、表示、管理は、 NTT CPaaS Web インターフェイスまたはサブスクリプション API を使用して行うことができます。

前提条件 [#prerequisites]

Webhook サブスクリプションを管理するには、次のものが必要です。

NTT CPaaSアカウント: 少なくとも1つの通信チャネルを有効にしたアカウントにログインまたは登録してください。
通信リソース: メッセージを送信するための電話番号、送信者 ID、または電子メールドメイン。リソースの取得に関するガイダンスは、「リソースと数値の概要」を参照してください。
Webhook エンドポイント: 通知を受信する準備ができている、パブリックにアクセス可能な URL。
通知プロファイル: 通知が配信される場所と方法を定義します。通知プロファイルの管理を参照してください。

サブスクリプションコンポーネントの概念の概要は、Webhookサブスクリプションについて(/subscriptions/understanding-subscriptions)を参照してください。

サブスクリプションの作成 [#create]

イベント通知を受信するチャネルごとにサブスクリプションを作成します。各サブスクリプションには、少なくとも 1 つのイベントと通知プロファイルが含まれている必要があります。

NTT CPaaS Web インターフェイスにログインし、開発者ツール > サブスクリプション管理 に移動します。
[サブスクリプション] タブを開きます。検索バーを使用して、特定のサブスクリプションを検索します。
サブスクリプションの作成 を選択します。
[カテゴリの選択] 画面で、カテゴリを選択します。
- チャネル: メール、Facebook、カカオ(Alim、ブランドメッセージング)、LINE、モバイルプッシュ、RCS、SMS、MMS、TikTok、Viber、WhatsApp、Zalo、Voice and WebRTC、Open チャネル、Apple Messages for Business
- 番号と送信者: 登録、モバイル ID、および番号検索
- ツール: ブロックリストと顧客エンゲージメント / AgentOS
サブスクリプション名とサブスクリプション ID を入力します。文字、数字、ダッシュ、アンダースコアのみを使用します。次に、次へを選択します。
[イベントの選択] 画面で、サブスクライブするイベントを選択し、[次へ] を選択します。チャネル別のイベントの完全なリストについては、利用可能なWebhookイベントを参照してください。

メモ
INBOUND_MESSAGEイベントを選択し、受信設定が番号レベルですでに定義されている場合は、その設定を更新し、転送アクションとして「サブスクリプションの適用」を設定します。詳細は、受信メッセージ:サブスクリプションルーティングを参照してください。
[フィルターの設定] 画面 (オプション) で、次の条件でイベントをフィルター処理します。
- User: 特定のユーザーに対して生成されるEvents
- エンティティ: 一意の顧客または部門を表すエンティティ ID
- アプリケーション: 特定のユースケースを表すアプリケーション ID
- リソース: 送信者名、番号、ドメイン、またはその他の識別子。送信トラフィックの場合、リソースフィルターは 送信者 と一致します。インバウンドトラフィックの場合、宛先と一致します。
複数のフィルターを組み合わせることができます。サブスクリプションは、すべてのフィルター条件が一致する場合にのみトリガーされます。空のままにしたフィルターはワイルドカードとして機能し、すべての値に一致します。たとえば、entityId なしで applicationId を設定すると、エンティティに関係なく、そのアプリケーションからのイベントが一致します。選択したカテゴリのすべてのイベントに適用するには、すべてのフィルターを空のままにします。次に、次へを選択します。
通知プロファイルを選択するか、新しいプロファイルを作成します。
- 新規作成する場合は、名前と Webhook URL を入力します
- 必要に応じて、応答本文の正規表現または応答正規表現を追加して、HTTP 応答を検証します
重要
サブスクリプションが機能するには、通知プロファイルが必要です。
(オプション)セキュリティ設定で、認証設定を選択するか、新しい認証設定を作成します。各方法の詳細は、認証設定の管理を参照してください。
(オプション)相互TLS(mTLS)セキュリティ用の証明書を適用します。

(オプション)詳細設定を構成します。

設定	範囲	説明
最大バケットサイズ	1 から 2000	要求あたりの最大イベント数
ウィンドウサイズ	20 から 10000	同時接続
接続タイムアウト	300〜30000ミリ秒	接続タイムアウト
読み取りタイムアウト	1000〜90000ミリ秒	読み取りタイムアウト
SSL プロトコル	TLS v1.2、v1.3	有効なSSLプロトコル
ヘッダー	キーと値のペア	リクエストで送信されるカスタムヘッダー
レート制限	1 から 5000	リクエスト数/秒

サブスクリプションの概要を確認し、 [保存] を選択します。

サブスクリプションの作成 API エンドポイントを使用します。要求パスでチャネルを指定します。

新しい通知プロファイルをインラインで作成するか、profileId で既存のプロファイルを参照できます。

subscriptionId は作成後に変更できません。

サブスクリプションを表示または編集する [#view-edit]

NTT CPaaS Web インターフェイスにログインし、開発者ツール > サブスクリプション管理 に移動します。
[サブスクリプション] タブを開き、検索バーを使用してサブスクリプションを検索します。
サブスクリプションの横にある 3 つのドットのメニューを選択し、次を選択します。
- 表示: 構成の概要を表示する
- 編集: イベント、フィルター、認証、または通知プロファイルを変更する
メモ
サブスクリプションのカテゴリまたはチャネルは変更できません。
変更を行い、保存を選択します。

サブスクリプションの削除 [#delete]

NTT CPaaS Web インターフェイスにログインし、開発者ツール > サブスクリプション管理 に移動します。
[サブスクリプション] タブを開き、検索バーを使用してサブスクリプションを検索します。
サブスクリプションの横にある 3 ドットメニューを選択し、[削除] を選択します。

重要

サブスクリプションを削除すると、他の構成された設定に影響を与える可能性があります。続行する前に、サブスクリプション階層と削除ルールを確認して、削除の依存関係を理解してください。

フィルターのベストプラクティス [#best-practices]

カバレッジ範囲を定義する

フィルターを使用して、サブスクリプションを作成する範囲を指定します。applicationId を設定すると、そのアプリケーションのイベントのみが対象となります。フィルターを空のままにすると、選択したチャネルのすべてのイベントが含まれます。

サブスクリプションの一意性を確保する

各サブスクリプションは個別である必要があります。同じチャネル、イベントタイプ、およびフィルター値を持つ 2 つのサブスクリプションを作成すると、システムは 2 番目のサブスクリプションを拒否します。

一致条件を理解する

サブスクリプションは、すべてのフィルター条件が受信イベントに一致する場合にのみトリガーされます。たとえば、applicationId=AppB と entityId=Template123 を設定した場合、その正確な組み合わせのイベントのみが一致します。

1 つのイベント、1 つのサブスクリプション

各イベントは 1つのサブスクリプションのみと一致します。これにより、一貫性のある配信が保証され、処理の重複が回避され、トラブルシューティングが容易になります。

関連ページ

利用可能なWebhookイベント
すべてのチャネル、番号サービス、プラットフォームツールからイベントを検索します。

通知プロファイルの管理
通知が配信される場所を設定します。

認証設定の管理
Webhook エンドポイントを Basic、HMAC、または OAuth で保護します。

受信メッセージのルーティング
サブスクリプションを介して受信メッセージをルーティングします。

サブスクリプションの階層と削除ルール
コンポーネントの関係と削除の依存関係。