Webhook チャネル接続ドキュメント

最終更新 2026/10/05

1. 概要

AEエンゲージモジュールのWebhook チャネルは、ダウンストリームにある顧客側のあらゆるメッセージシステムまたは類似メッセージシステムと接続するためのAPIを定義しています。顧客は比較的軽量なREST APIの連携開発を行うだけで、AEエンゲージモジュールに組み込まれていないプッシュチャンネルにすばやく対応できます。具体的な呼び出しの流れは下図を参照してください：

まず、AEエンゲージモジュール（Engage）がAEプラットフォームのイベントデータとユーザーデータを使用して、ターゲットグループを計算します。
ターゲットグループに合わせて、メッセージの内容を組み立てます。AEエンゲージモジュールは、設定されたwebhookチャンネルサービスにHTTPリクエストをバッチごとに送信します。
お客様のwebhookチャンネルサービスはhttpの呼び出しを受け取ってリクエスト内容を取得した後、形式の変換、他の業務データとの結合、非同期処理キューへの投入などの操作を独自に行い、最終的に社内外の任意のメッセージ/類似メッセージシステムを呼び出すことができます。呼び出し先となるシステムの例：

ゲームのメールシステム
ゲームのお知らせシステム
アカウント停止システム
SMSシステム
サードパーティのプッシュシステム

処理が完了したら（非同期処理のフローは含みません）、取り決めた形式で今回のリクエストの処理結果を返します。処理に失敗したデータがある場合は、そのデータの番号と失敗の原因を明確に返す必要があります。AEエンゲージモジュールは、処理に失敗したデータを記録します。
レシートイベントデータの回収（任意）

ゲームのメールシステムにプッシュする場合は、ユーザーがゲーム内メールを開いたときにトラッキングを行い、「メールのクリック」をプッシュクリックのトラッキングイベントとして、取り決めに従って関連するパススルーパラメータを付与します。これにより、リーチ段階のファネル分析をより正確に行えます。

2. Webhook チャネルサービス

AEエンゲージモジュールのWebhook チャネルと連携するには、HTTP Endpoint Serverを開発する必要があります。準拠すべきAPI定義は以下のとおりです。

2.1 入力・出力パラメータの形式定義

Webhook チャネルのRequest

サービスの入力パラメータはAEエンゲージモジュールが構築・生成し、POST方式で送信します。Content-Typeはapplication/jsonに設定します。リクエスト本文request_bodyはJSONArrayで、1バッチで複数のメッセージデータを送信できます。各メッセージデータは、1人のユーザーに特定の内容のメッセージを送信することを表します。

ヒント

注意：AEエンゲージモジュールのWebhook チャネルは、1つのリクエスト本文に複数ユーザー分のトリガーメッセージを含めます。これは、ダウンストリーム側でまとめて処理しやすくし、送信効率を高めるためです。1バッチに含めるユーザー数はカスタマイズできます。

パラメータの例は次のとおりです：

// リクエストの入力パラメータの形式
[
    {"push_id":"accountid123987001","custom_params":{"gameuid":"123acb001","name":"山田太郎",...},"params":{"title":"デイリーイベント",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
    ,{"push_id":"accountid123987002","custom_params":{"gameuid":"123acb002","name":"佐藤花子",...},"params":{"title":"デイリーイベント",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// 各メッセージの入力パラメータの形式
{
    //チャンネルの送信ID。通常はユーザーの一意のID（アカウントIDやキャラクターIDなど）です。エンゲージ担当者が'AEエンゲージモジュール-チャンネル管理'で定義します
    "push_id": "accountid123987001",
    
    //テンプレートパラメータ。このパラメータ配下の具体的なパラメータ内容は'AEエンゲージモジュール-チャンネル管理'で定義できます
    "params": {
        "title": "デイリーイベント",
        "content": "山田太郎さん、こんにちは。イベントにぜひご参加ください！",
        //オブジェクトグループ
        "attachment": [
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        ]
    },
    //カスタムパラメータ。ユーザープロパティを渡すことができます。このパラメータ配下の具体的なパラメータ内容は'AEエンゲージモジュール-チャンネル管理'で定義できます
     "custom_params": {
         "zone_id":"17281",
         "name": "山田太郎"
    },
    //チャンネルのレシートプロパティ。このパラメータはAEエンゲージモジュールのシステムがデフォルトで追加し、後続のデータ統計に使用します。通常、業務側で解析する必要はなく、ダウンストリームにそのままパススルーすれば問題ありません。ダウンストリームで送信する際は、このjsonオブジェクトをそのまま送信し、toStringしてから送信しないよう注意してください
    "#ops_receipt_properties": {   
        "ops_project_id": 1,  //AEのプロジェクトIDに対応
        "ops_task_id": "0050", //1つのエンゲージタスクに対応。エンゲージタスクでプッシュする場合のみ付与
        "ops_task_instance_id": "0050_2023-01-01",  //1回のエンゲージタスクインスタンスに対応。エンゲージタスクでプッシュする場合のみ付与
        "ops_task_exec_detail_id": "17795",  //タスクインスタンスの1回のプッシュに対応。エンゲージタスクでプッシュする場合のみ付与
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", //1回のプッシュにおける1回のbatchリクエストに対応。同じリクエスト内のops_request_idはすべて同じで、リクエストを再試行してもこのIDは変わりません。顧客の業務システムでリクエストの冪等性チェックを行う場合は、このフィールドを使用できます。エンゲージタスクでプッシュする場合のみ付与。
        "ops_exp_group_id": "122", //エンゲージタスクのA/BテストのテストグループIDに対応。エンゲージタスクでA/Bテストを有効にした場合のみ付与
        "ops_flow_id":"0050", //1つのフローキャンバスに対応。フローキャンバスのアクションノードから配信する場合のみ付与
        "ops_flow_version":"V_20251010_1", //フローキャンバスのバージョン番号。フローキャンバスのアクションノードから配信する場合のみ付与
        "ops_node_id":"1001", //フローキャンバスのノードID。フローキャンバスのアクションノードから配信する場合のみ付与
        "ops_push_language": "default"  //プッシュ言語に対応。多言語でプッシュする場合に付与
       
    }
}

パラメータ名	パラメータタイプ	必須	パラメータの説明	備考
push_id	String	はい	プッシュID	具体的なパラメータフィールドは'エンゲージ設定-チャンネル管理-送信ID'で定義できます
params	Object	いいえ	テンプレートパラメータ	プッシュ時にエンゲージ担当者が入力するチャンネルパラメータ（プッシュ内容など）です。具体的なパラメータ内容は'エンゲージ設定-チャンネル管理-コンテンツテンプレート'で定義できます
custom_params	Object	いいえ	カスタムパラメータ	システムが自動的に付与する、プッシュ対象ユーザーのユーザープロパティです。具体的なパラメータ内容は'エンゲージ設定-チャンネル管理-カスタムパラメータ'で定義できます
#ops_receipt_properties	Object	はい	AEエンゲージモジュールのレシートフィールド	AEエンゲージモジュールのシステムがデフォルトで追加します。ダウンストリームシステムでメッセージのクリック状況を確認する必要がある場合は、クリックイベントでこのフィールドをそのままパススルーして送信する必要があります。タスクの目標設定のコンバージョンイベントでは、このフィールドを送信する必要はありません

テンプレートパラメータ、カスタムパラメータのKeyの命名規則：アンダースコア区切りで命名します。パラメータは英数字とアンダースコアで構成し、先頭の文字はアンダースコアまたは英字のみとします。注意：paramsとcustom_paramsのパラメータでは、すべてのタイプのデータ(整数、小数、日付などのタイプ)が、リクエストの送信時にすべて文字列に変換して処理されます

Webhook チャネルのResponse

パラメータの例は次のとおりです：

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // fail_listの各要素は失敗したオブジェクトの情報で、エラー情報とエラーオブジェクトの番号を含みます。エラーオブジェクトの番号は1から始まります。例：5件のオブジェクト情報を送信し（番号は1～5）、3件成功・2件失敗し、そのうち2件目と4件目が失敗した場合は、次のように返します
        "fail_list": [{
            "index": 2,
            "message": "プッシュ対象のプレイヤーのtoken情報が存在しません"
        }, {
            "index": 4,
            "message": "push id not found"
        }]
    }
}

パラメータ名	パラメータタイプ	必須かどうか	パラメータの説明
return_code	Integer	はい	リターンコード。0は成功（または部分成功）、1は失敗を表します
return_message	String	いいえ	リターンメッセージ
data	Object	いいえ	レスポンスデータ
data.fail_list	Array	いいえ	return_code=0の場合、 data.fail_listが[]またはnullのときは、すべて成功とみなされます data.fail_listが空でない場合は一部失敗となり、失敗の詳細はlistに定義されたとおりです。業務上、一部失敗が発生しない場合は、そのまま[]を渡してください。注意：一部の利用できないPushIdのチェックは、インターフェースの処理ロジックで事前に行い、fail_listでAEに返すことをお勧めします。これにより、タスクのプッシュ成功指標の統計がより正確になります。失敗リスト内のオブジェクトのindexプロパティは番号を表し、番号は1から始まります。0からではありません！ messageフィールドは必須ではありませんが、異常時の問題調査に役立つため、返すことを強くお勧めします。 return_code=1の場合は、data.fail_listに何が渡されていても、すべて失敗とみなされます。

2.2 リクエストの認証

この手順の設定が完了したら、Webhook チャネルの製品画面で有効にできます。

認証機能はデフォルトでは無効です。Webhook チャネルのserverで認証が不要な場合は、このセクションをスキップできます。認証に対応する場合は、チャンネルの設定時に認証スイッチをオンにする必要があります。送信側は署名をhttpリクエストヘッダーに追加します。KeyはX-TE-OPS-Signatureです。サーバー側では、シークレットキーとRequest Bodyに基づいてHmacSHA1署名を行ってsignatureを生成し、送信側の署名と比較する必要があります。一致すれば認証成功となります。署名アルゴリズムのJava実装例：

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
   HmacSHA1署名アルゴリズム
   
   secretKeyは顧客が設定したシークレットキー
   requestBodyはリクエスト内容のJSONString
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
    String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody)
    return signature;
}

署名アルゴリズムのPHP実装例：

/**
 * HmacSHA1署名アルゴリズム
 * @param $secretKey : 顧客が設定したシークレットキー
 * @param $requestBody : リクエスト内容のJSONString
 * @return string 署名値
 */
function HmacSHA1($secretKey, $requestBody) {
    return hash_hmac('sha1', $requestBody, $secretKey);
}

2.3 リクエストの同時実行性能

メッセージのプッシュ速度を確保するため、Webhook チャネルサービスが対応できる同時実行数は高いほど望ましく、100 TPS以上に対応できることを推奨します。また、AEのエンゲージモジュールでは、ダウンストリームのWebhook チャネルサービスの同時実行能力の上限に合わせて、レート制限を設定できます。

2.4 リクエストと結果の完全なテスト例

// リクエスト情報
curl -X POST "http://localhost:8999/v1/webhook_channel/test/sample" 
-H "accept: */*" 
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Type: application/json" 
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"custom_params\":{\"name\":\"山田太郎\"},\"params\":{\"title\":\"デイリーイベント\",\"content\":\"山田太郎さん、こんにちは。イベントにぜひご参加ください！\"},\"#ops_receipt_properties\":{\"ops_task_id\":\"0050\",\"ops_request_id\":\"f7b66eb7-3363-4a46-a402-601a64b45f76\",\"ops_task_instance_id\":\"31\",\"ops_project_id\":1}}]"

// 返される結果
{
  "data": {
      "fail_list": []
  },
  "return_code": 0,
  "return_message": "success"
}

3. Webhook チャネルの設定可能なパラメータ

以下のパラメータはデフォルトでバックエンドで設定されています。変更が必要な場合は、ThinkingAIのカスタマーサクセスにお問い合わせください

構成項目	指定可能な値	デフォルト値	設定の説明
送信のレート制限	-1，[1,10000]	制限なし	単位：回/秒。-1に設定すると制限なしになります。1～10000の数値（例：500）に設定すると、ダウンストリームのWebhook チャネルサーバーへのリクエストは1秒あたり最大500回になります。
送信バッチサイズ	[1,500]	100	1回の呼び出しパラメータのJsonArrayに含まれる要素数を表します。バッチサイズを大きくすると、メッセージ送信の効率を高められます。バッチサイズを小さくすると、送信速度は遅くなりますが、信頼性は高くなります。推奨値は100で、最大500まで設定できます。
タイムアウト時間	[0,3600]	60	単位：秒。httpリクエストのsocketタイムアウト時間で、デフォルトは60sです。<=0に設定した場合は、タイムアウトしません。
失敗時の再試行回数	[0,10]	0	業務上の重複プッシュを避けるため、デフォルトは0回（再試行しない）です。>0の値を設定した場合、インターフェースがタイムアウトするか、インターフェースがreturn_code!=0を返すと、再試行のロジックが実行されます。
失敗時の再試行間隔	[0,600]	5	単位：秒。デフォルトでは5sごとに1回再試行します。
戻り値の強バリデーション	有効、無効	有効	有効にすると、AEエンゲージモジュールのサービスはダウンストリームサーバーが返したresponseの形式を検証し、上記のWebhook チャネルのresponseパラメータの定義規則に合致しない場合は失敗とみなします。例：タイムアウト時間を5sに設定した場合、返り値の強バリデーションを有効にしていなければ、Webhook チャネルサービスが5s以内に正常に応答し、返り値がHTTP 200でBodyなしのとき、AEエンゲージモジュールは今回の呼び出しを成功とみなします。返り値の強バリデーションを有効にしている場合は、Webhook チャネルサービスが5s以内に正常に応答しても、返り値がHTTP 200でBodyなし、またはBodyの形式が取り決めた規則と一致しないとき、AEエンゲージモジュールは今回の呼び出しを失敗とみなします。

4. チャンネル設定画面の例

新建 Webhook 通道表单：通道名称、URL、发送 ID，打开通道鉴权和触达漏斗设置

パラメータ	説明	備考
チャンネル名	Webhook チャネルの名前（表示、選択に使用）	一意性チェック
URL	メッセージのプッシュを受け取るインターフェースのURL	同じURLで複数のチャンネルを設定できます
送信ID	メッセージを受け取るターゲットユーザーのIDタイプです。例えば、メールの送信ではユーザーのキャラクターID(role_id)を使用します	送信IDはユーザープロパティとして送信する必要があります。ターゲットユーザー数の推定時には、送信IDが空のユーザーは除外されます
カスタムリクエストヘッダー	リクエスト送信時に付加するカスタムHTTPリクエストヘッダーです。Authorization、API Key、業務識別子などを渡すために使用します	デフォルトは無効です。必要に応じて有効にできます。最大10個まで設定でき、ヘッダー名は大文字と小文字を区別しません
チャネル認証	カスタムのチャンネル認証方式	デフォルトは無効です。必要に応じて有効にできます
リーチファネル設定	ファネルステップに関連付けるメタイベント名	任意で有効化
コンテンツテンプレート	このチャンネルからユーザーに送信する具体的な内容のテンプレートです。テキスト、動的テキスト、数値、オブジェクトグループなどのフィールドタイプに対応しています。例えば、メール送信チャンネルでは、オブジェクトグループタイプでアイテムの内容（アイテムIDとアイテム数）を設定し、リーチタスクのフロントエンド画面に表示して、エンゲージタスクを設定するエンゲージ担当者が入力できるようにします	フィールド：パラメータの名前で、送信時にメッセージ本文で使用します。表示名：タスク作成時に表示されるフィールドです。入力方法：テキスト、動的テキスト、数値、単一選択ドロップダウン、日付、時間、オブジェクトグループ。デフォルト値：任意。入力方法を選択した後に入力します。ヒント：タスク作成時の入力欄のヒントです（任意）。必須：チェックを入れると必須になります。デフォルトではチェックされていません
カスタムパラメータ	チャンネルの要件に応じて任意で追加します。このパラメータはパススルーされます	任意。フィールド：パラメータの名前で、送信時にメッセージ本文で使用します。関連フィールド：フィールドに関連付けるユーザープロパティで、メッセージ本文の送信時にはこのプロパティ値がフィールド値として使用されます。デフォルト値：任意。デフォルト値を設定した場合は、プロパティ値が空のときにデフォルト値を使用します。デフォルト値を設定していない場合は、プロパティ値が空のときに空の値を返します

5. プッシュクリックイベントの収集

Webhook チャネルでプッシュしたメッセージについては、必要に応じてクライアント/サーバー側でクリックイベントを収集できます。収集方法はThinkingAIのデータ連携マニュアルにあるイベントの送信方法を参照してください。イベント名はカスタマイズできます。イベントデータでは、Webhook チャネルで配信されたメッセージ内の#ops_receipt_propertiesフィールドを取得し、全体を1つのオブジェクトプロパティとして送信します。他の分析シナリオがある場合は、このイベントに他のフィールドプロパティを追加することもできます。注意：プロパティのフィールド名は必ず#ops_receipt_propertiesとし、タイプはオブジェクトとします。勝手に変更しないでください。フィールド名を変更したり、フィールド内部の内容を変更したり、誤ってフィールドをテキストプロパティとして送信したりすると、以降のデータ利用で異常が発生しますコード例：

JSONObject properties = new JSONObject();
//Webhook チャネルから配信されたmessageのメッセージ本文から、json構造のops_receipt_propertiesオブジェクトを取得し、全体を1つのオブジェクトプロパティとして送信
JSONObject opsReceiptProperties = message.get("#ops_receipt_properties");
//注意：プロパティ名は必ず #ops_receipt_properties とし、勝手に変更しないでください。イベント名はカスタマイズできます
properties.put("#ops_receipt_properties",opsReceiptProperties);
//propertiesオブジェクトの内容の例： "#ops_receipt_properties":{"ops_task_id":"0062","ops_project_id":2,"ops_task_instance_id":"62","ops_request_id":"967ea854-2c42-490b-9c33-c1792ea637ec"}
instance.track("ops_push_click",properties);

このページは役に立ちましたか？

1. 概要​

2. Webhook チャネルサービス​

2.1 入力・出力パラメータの形式定義​

Webhook チャネルのRequest​

Webhook チャネルのResponse​

2.2 リクエストの認証​

2.3 リクエストの同時実行性能​

2.4 リクエストと結果の完全なテスト例​

3. Webhook チャネルの設定可能なパラメータ​

4. チャンネル設定画面の例​

5. プッシュクリックイベントの収集​