Webhook のレポート

Webhook を使用すると、15 を超えるメッセージングチャネルとプラットフォームサービスで NTT CPaaS からのイベント通知を受信できます。NTT CPaaSは、配信状況、クリック数、開封確認、受信メッセージなどのイベントが発生した瞬間に、エンドポイントにPOSTリクエストを送信します。

Webhook は、リアルタイムのイベント処理が必要な場合、独自のシステムにデータを格納する場合、またはマルチテナントプラットフォームを構築する場合に使用します。次の 2 つの構成方法を使用できます。

リクエストごと: API を介して各メッセージを送信するときに、Webhook URL を指定します。
Webhook サブスクリプション: サブスクリプション管理を使用して、フィルタリングとセキュリティを備えたチャネルレベルの通知を構成します。

分析またはスケジュールされたエクスポートが必要な場合、組み込みのレポートツールを使用すると、セットアップが少なくて済みます。

カバレッジ

サポートされているすべてのチャネル、サービス、プラットフォームイベントのすべてのイベントタイプの完全なカタログについては、イベントサブスクリプションリファレンスを参照してください。

Webhook は、次のチャネルとプラットフォームサービスでサポートされています。

Webhook はデータを保存しません。Eventsはリアルタイムでプッシュされ、NTT CPaaSは保持しません。

構成方法

Webhook は、次の 2 つの方法で構成できます。

作り方	説明	最適な用途
要求ごと	各メッセージを送信するときに Webhook URL を指定します。パラメータは API のバージョンによって異なります。 • `deliver`: `url`、`contentType`、`notify` を使用します。 • レガシー: `notifyUrl` と `notifyContentType` を使用します。正確なパラメーターについては、チャネル API リファレンスを参照してください。	メッセージレベルの制御。メッセージごとに異なるエンドポイント
Webhook サブスクリプション	サブスクリプション管理 Web インターフェイスまたはサブスクリプション API を使用して、チャネルレベルのサブスクリプションを構成します。エンドポイント URL、セキュリティ設定、イベントフィルターをチャネルごとに設定します。Events は、チャネル Webhook スキーマで定義されたペイロード形式で URL に到着します。	フィルタリング、セキュリティ、またはチャネルごとに個別のエンドポイントを必要とするスケーラブルなセットアップ

通知プロファイル、セキュリティ設定、チャネルごとに利用可能なイベントなど、サブスクリプション設定ガイドの詳細については、[サブスクリプションのドキュメント]を参照してください。

要求ごとまたはサブスクリプション [#per-request-or-subscriptions]

アスペクト	リクエストごとの Webhook	サブスクリプション
セットアップ	各 API リクエストで URL を指定する	サブスクリプション API を使用して一度構成する
フィルタリング	Webhook レベルではなし	アプリケーション、エンティティ、ユーザー、リソース別
安全	標準 HTTPS	組み込み認証(Basic、HMAC、OAuth)とmTLS

詳細な比較については、サブスクリプションとメッセージごとのWebhookの選択を参照してください。

Webhook イベントの種類

Webhook ペイロードは、イベントタイプとチャネルによって異なります。イベントの種類によって、Webhook をトリガーしたものと、ペイロードに含まれるフィールドが決まります。

NTT CPaaS Webhook は、大きく 2 つのカテゴリに分類されます。

メッセージングイベント: 送受信したメッセージのアクティビティ(ステータスの変更、受信返信、受信者のやり取り)によってトリガーされます。使用可能なイベントタイプとペイロードフィールドは、チャネルによって異なります。
プラットフォームサービスイベント: 非同期サービスリクエストが完了するとトリガーされます (モバイルID, 番号検索, ブロックリスト)。これらは、サービス固有のスキーマを使用します。

最も一般的なイベントカテゴリは次のとおりです。チャネル別のすべてのイベントの完全なリストは、「利用可能なWebhookイベント](/subscriptions/available-events)」を参照してください。

イベントタイプ	何が引き金になるのか	供給状況	スキーマの例
`DELIVERY`	メッセージは最終ステータス (配信済み、失敗済み、期限切れ、拒否済み) に達します。ステータス、エラーコード、タイミング、価格、および元のリクエストのフィールドが含まれます。	サポートされているすべてのメッセージングチャネル	SMS配信レポート
`INBOUND_MESSAGE`	サブスクライバーは、あなたが所有する番号またはアドレスにメッセージを送信します。送信者、コンテンツ、タイムスタンプ、価格が含まれます。	双方向メッセージングをサポートするチャネル	SMS インバウンドメッセージ
`CLICK`	受信者がメッセージ内の短縮 URL をクリックします。URL、受信者のデバイスタイプ、OS、および位置情報が含まれます。URL の短縮とトラッキングを有効にする必要があります。	URL トラッキングをサポートするチャネル	SMS追跡通知
`SEEN`	受信者がメッセージを表示します(開封確認)。	WhatsApp, RCS, Viberビジネスメッセージ, カカオブランドメッセージ	WhatsApp で表示されたレポート
プラットフォームサービスの成果	非同期サービス要求が完了します(モバイルID検証、番号検索、ブロックリストの変更)。スキーマはサービスによって異なります。	モバイルID、番号検索、ブロックリスト	ブロックリストイベント

配信 Webhook 間の共通フィールド [#common-fields]

配信 Webhook には、システム生成フィールド (配信ステータス、エラーの詳細、タイミング、ネットワークコード、価格) と、送信リクエストのオプションフィールドが含まれます。完全なスキーマは API リファレンスにありますが、次のフィールドはほとんどの配信 Webhook ペイロードに表示されます。

フィールド	説明
'メッセージ ID'	照合と追跡のための一意のメッセージ識別子。常に存在します。設定されている場合はカスタム値を返し、それ以外の場合は自動生成された NTT CPaaS ID を返します。
`bulkId`	グループ化されたメッセージまたは複数の受信者の一括識別子。動作は API のバージョンによって異なります。自動生成され、常に「配信」API に存在します。レガシー API で設定されている場合にのみ存在します。
'コールバックデータ'	カスタムデータ:注文ID、参照、またはメタデータ。要求で設定されている場合は存在します。省略すると不在。最大長はチャネルによって異なります: データペイロードを参照してください。
`campaignReferenceId`	分析と整理のためのキャンペーン追跡 ID。要求で設定されている場合は存在します。省略すると不在。
`entityId` と `applicationId`	マルチテナントエンティティとアプリケーション識別子。動作は API のバージョンによって異なります: 詳細については、チャネル API リファレンスを参照してください。

contentType は、配信レポートのペイロード形式 (application/json または application/xml) を設定します。詳細については、 SMS API リファレンスを参照してください。

プッシュ通知の再試行サイクル

エンドポイントが使用できない場合、NTT CPaaS は次の式を使用して再試行します。

1 min + (1 min × retryNumber²)

再試行は 0 から番号が付けられるため、最初の再試行では retryNumber は 0 です。最大再試行回数は 20 回です。最後の再試行は、最初の試行から 41 時間 30 分後に行われます。エンドポイントが再試行期間全体にわたって使用できない場合、イベントは失われ、回復できません。

次の表は、最初の 7 回の再試行を示しています。

再試行	前回以降の遅延	最初の試行からの時間
0	1分	1分
1	2分	3分
2	5分	8分
3	10分	18分
4	17分	35分
5	26分	1時間01分
6	37分	1 時間 38 分

アクセス方法の比較 [#access-method-comparison]

すべての状況が Webhook に適しているわけではありません。以下の表は、NTT CPaaSからメッセージイベントデータを取得する3つの方法(Webhook、ポーリング、ログ)を比較したものです。

メカニズム	仕組み	いつ使用するか
Webhook (ウェブフック)	NTT CPaaSがリアルタイムでエンドポイントにイベントをプッシュ	リアルタイム処理;イベントによってトリガーされるビジネスロジック
投票	デリバリーレポートのバッチをオンデマンドでフェッチします (過去 48 時間、取得時に消費)	パブリックエンドポイントを公開できない場合。各チャネルには独自のポーリングエンドポイントがあります(たとえば、SMSの場合: アウトバウンドSMS配信レポートの取得)。他のチャネルについては、チャネル API リファレンスを参照してください。
ログ	メッセージアクティビティの読み取り専用レコードを照会します (過去 48 時間、未消費)	Web インターフェイスでのメッセージ履歴の表示。各チャネルには独自のログエンドポイントがあります。例: SMS 送信ログ。その他のチャネルについては、チャネル API リファレンスを参照してください。詳細はメッセージログを参照してください。

トラブルシューティング

問題点	ソリューション
Webhook エンドポイントがイベントを受信しない	エンドポイントがパブリックにアクセス可能であり、HTTP 200 を返すことを確認します。ファイアウォールルールを確認します。Webhook URL が要求またはサブスクリプションで正しく構成されていることを確認します。
ダウンタイム後に停止したEvents	エンドポイントが再試行期間全体にわたって使用できなかった場合、イベントは失われ、回復できません。メッセージログを使用して、影響を受ける期間の個々のメッセージの状態を確認します。
パブリックエンドポイントを公開できない	代わりにポーリングを使用してください。アクセス方式比較のポーリング行を参照してください。

関連ページ

メトリック API
集計されたパフォーマンスデータを、単一のエンドポイントを介してすべてのチャネルにわたってプログラムでクエリします。

メッセージログ
Analyze インターフェイスまたは Logs API を使用して、メッセージごとの配信ステータスと詳細にアクセスします。