Webhook構成接続ドキュメント

最終更新 2026/10/03

1. 概要

構成センターのWebhook チャネルは、外部システムや内部の他のモジュールと相互に通信するための接続メカニズムを確立することを目的としています。Webhookを通じて、構成センターは特定のデータを指定された受信側に送信できます。受信側は相応の処理を行うことで、構成センターのデータとの同期、特定の操作の実行、データのさらなる配信などの機能を実現できます。

2. Webhook チャネルサービス

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

Webhook チャネルのRequest

入力パラメータの方式：構成センターが構築・生成し、POST方式でリクエストを送信します
Content - Type：application/jsonに設定します
リクエスト本文の構造：リクエスト本文request_bodyはJSONArrayで、1バッチで複数のメッセージデータを送信できます。各メッセージデータは、特定の構成項目に関連するメッセージを表します
入力リクエストの形式：デフォルトのリクエストパラメータの形式は次のとおりです

[{
    "opType": "${opTypeValue}",
    "configInfo": {
        "configId": "${configIdValue}",
        "templateId": "${templateIdValue}",
        "strategyId": "${strategyIdValue}"
    },
    "targetType": "${targetTypeValue}",
    "targetEnv": ${targetEnvValue},
    "targetAudience": ${targetAudienceValue},
    "configParams": ${configParamsValue},
    "#ops_receipt_properties": ${#ops_receipt_propertiesValue},
    "isEndPush": ${isEndPushValue}
}]

上記のパラメータ名はカスタマイズできます。調整が必要な場合は、ThinkingAIのサポート担当者にお問い合わせください

パラメータ名	パラメータタイプ	パラメータの説明	備考
opType	文字列	${opTypeValue}はプレースホルダーです（以下同様）。デフォルトの値はonline、suspend、offlineで、それぞれ画面での「オンライン」（編集後の再オンラインを含む）、「一時的に無効化」、「オフライン」の操作に対応します。	戦略の期限切れによるオフライン時は、デフォルトでオフライン通知を配信しません。有効にするには、ThinkingAIのサポート担当者にお問い合わせください。
configId	文字列	構成項目IDは、接続する1つの業務モジュールを識別するために使用します	構成項目の説明は構成項目管理を参照してください
templateId	文字列	テンプレートIDは、具体的な業務機能の形式を識別するために使用します。	テンプレートの説明は構成テンプレート管理を参照してください
strategyId	文字列	戦略IDは構成戦略の一意のIDで、戦略のライフサイクル全体の管理に使用します。	戦略の説明は構成戦略管理を参照してください
targetType	文字列	targetTypeの値はall/targetEnv/targetAudienceで、それぞれすべて、環境レベル構成、ユーザーレベル構成に対応します。	目標環境とターゲットユーザーの説明は、構成戦略管理の「ターゲットユーザー」の部分を参照してください
systemId (任意)	JSON	構成センターで複数のダウンストリームシステムと連携する場合は、システムドッキングIDを有効にできます。有効にすると、ユーザーレベル構成のオンラインリクエストは、システムドッキングIDのフィールド値ごとにパッケージを分割して配信されます。一時停止またはオフラインの操作時も、リクエストに対象システムの値がすべて含まれます。これにより、Webhookサービスで中継処理を行いやすくなります。	システムドッキングIDの設定は構成チャンネル設定を参照してください
targetEnv	JSON	画面で設定した目標環境の条件です。webhook serverで解析・処理する必要があります。環境条件の形式の例は、2.2の戦略オンラインリクエストを参照してください。複数の条件はかつの関係です。	一時的な無効化とオフラインのリクエストを配信する場合、このパラメータは含まれません
targetAudience	JSONArray	ターゲットユーザーのリストです。ユーザー情報については、Webhook チャネルでユーザープロパティをカスタムパラメータとして追加する必要があります。構成チャンネル設定の「ユーザーパラメータ」の部分を参照してください。	一時的な無効化とオフラインのリクエストを配信する場合、このパラメータは含まれません
configParams	JSON	構成テンプレートで設定した具体的なパラメータ内容です。	一時的な無効化とオフラインのリクエストを配信する場合、このパラメータは含まれません
#ops_receipt_properties	JSON	パススルーパラメータです。戦略の自動分析に使用します。現時点では処理は不要です。	AEエンゲージモジュールのシステムがデフォルトで追加します
isEndPush	ブール値	今回のプッシュが終了したかどうかを示す識別子です。ユーザーレベル構成の配信が完了したときにのみ配信されます。

注意：targetAudienceとconfigParamsのパラメータでは、すべてのタイプのデータ（整数、小数、日付など）が、リクエストの送信時に「文字列」タイプとして送信されます。

2.2 例

戦略オンラインリクエスト

環境レベル構成の配信

「serverId」を環境条件とする例

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "targetType": "targetEnv",
    "syetemId": {   // システムドッキングIDを有効にした場合のみ、このパラメータを配信
        "serverId":["101","102"]
    },
    "targetEnv": {
        "serverId":["101","102"]
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "878c14fd1f266a16e8ba795085219ab0",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

ユーザーレベル構成の配信

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121002"
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "targetType": "targetAudience",
    "syetemId": { // システムドッキングIDを有効にした場合のみこのパラメータがあり、システムドッキングIDの値ごとにユーザーパッケージを分割して配信
        "serverId":["101"]
    },
    "targetAudience": [{
        "#user_id": "996080782348914698",
        "accountID": "jsxzdym",
        "serverID": "12"
    }, {
        "#user_id": "1308438872845193216",
        "accountID": "jsnjddk",
        "serverID": "16"
    }],
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "e0c24f7e5b05bfbccb72bdf56903d1e3",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121002"
    }
}]

システムドッキングIDを有効にすると、戦略を編集して新しいバージョンをオンラインにする際、オンラインリクエストの前に、その戦略がこれまでにカバーしたすべてのシステムへ戦略変更通知が配信されます。これはダウンストリームでの履歴データの処理に使用します。この通知は、システムドッキングIDを有効にした場合にのみ配信されます。

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121002"
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "targetType": "targetAudience",
    "syetemId": {    // 戦略がこれまでにカバーしたシステム値のリスト
        "serverId":["101", "102", "103"]
    },
    "targetAudience": [],
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "e0c24f7e5b05bfbccb72bdf56903d1e3",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121002"
    }
}]

戦略のオンラインはデフォルトでバッチごとにプッシュされます。以下はプッシュ完了の識別子です。

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "isEndPush": true,
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "9ea9b1f599774987d03c0a838b9aa14d",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

戦略の一時的な無効化リクエスト

[{
    "opType": "suspend",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "syetemId": {  // システムドッキングIDを有効にした場合のみこのパラメータがあります
        "serverId":["101","102"]
    },
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "0b33c3fc4b5c0a25c5a7122788f6c952",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

戦略オフラインリクエスト

[{
    "opType": "offline",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "syetemId": {  // システムドッキングIDを有効にした場合のみこのパラメータがあります
        "serverId":["101","102"]
    },
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "0b33c3fc4b5c0a25c5a7122788f6c952",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

2.3 Webhook チャネルのResponse

次のパラメータ形式でリクエストに応答してください。

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // fail_listの各要素は失敗したオブジェクトの情報で、エラー情報とエラーオブジェクトの番号を含みます。エラーオブジェクトの番号は1から始まります。例：5件のオブジェクト情報を送信し（番号は1～5）、3件成功・2件失敗し、そのうち2件目と4件目が失敗した場合は、次のように返します
        "fail_list": [{
            "index": 2,
            "message": "system error"
        }, {
            "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に定義されたとおりです。業務上、一部失敗が発生しない場合は、そのまま[]を渡してください。注意：インターフェースの処理ロジックで事前チェックを行い、fail_listでAEに返すことをお勧めします。これにより、タスクのプッシュ成功指標の統計がより正確になります。失敗リスト内のオブジェクトのindexプロパティは番号を表し、番号は0からではなく1から始まります！ messageフィールドは必須ではありませんが、異常時の問題調査に役立つため、返すことを強くお勧めします return_code=1の場合、data.fail_listに何が渡されていても、すべて失敗とみなされます。

2.4 リクエストの認証

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

認証機能はデフォルトでは無効です。Webhook チャネルのserverで認証が不要な場合は、このセクションをスキップできます。

認証に対応する場合は、チャンネルの設定時に認証スイッチをオンにする必要があります。送信側は署名をhttpリクエストヘッダーに追加します。KeyはX-AE-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.5 リクエストの同時実行性能

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

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

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

構成項目	指定可能な値	デフォルト値	設定の説明
構成センター専用のhostノード	具体的なhost	なし	デフォルトでは分離しません。分離が必要な場合は、複数のノードをカンマ区切りで設定します。例：ta4,ta5
構成センターのwebhookリクエスト形式	具体的なjson	なし	デフォルトの形式テンプレートは上記の例を参照してください。既存のインターフェースに接続する予定で、プッシュ成功ユーザーを区別する必要がないシナリオでは、リクエスト形式テンプレートをカスタマイズすることで、開発なしで既存のサービスに直接接続できます。
「1回のリリース終了」ステータス通知の送信	有効、無効	有効	ターゲットユーザータイプのオンラインプッシュで、含まれるユーザー数が多い場合は、パッケージを分割してWebhookサーバーにプッシュします。サーバー側で今回のプッシュが完了したかどうかを判断する必要がある場合は、このリクエストに基づいて判断できます。
自動オフライン時にリクエストを配信するかどうか	有効、無効	無効	戦略が設定された時刻に自動的にオフラインになった場合、デフォルトではWebhookサーバーにオフラインリクエストを送信しません。有効にすると、自動オフライン時にもオフラインリクエストが送信されます。形式は手動オフラインと同じです。
構成項目の配信コマンドタイプ	3種類、5種類	3種類	デフォルトはonline、offline、suspendの3種類です。編集後のオンライン（re_online）と強制オフライン（force_offline）を区別するように設定することもできます。
送信のレート制限	-1，[1,10000]	制限なし	単位：回/秒。-1に設定すると、レート制限なしになります。1-10000の数値（例：500）に設定すると、ダウンストリームのWebhook チャネルサーバーへ1秒あたり最大500回のリクエストを送信します。
送信バッチサイズ	[1,5000]	1000	1回の呼び出しパラメータのJsonArrayに含まれる要素数を表しますバッチサイズを大きく設定すると、メッセージ送信の効率を高められますバッチサイズを小さく設定すると、送信速度は遅くなりますが、信頼性は高くなります 1000に設定することを推奨します。最大5000まで設定できます
タイムアウト時間	[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エンゲージモジュールは今回の呼び出しを失敗とみなします

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

1. 概要​

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

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

Webhook チャネルのRequest​

2.2 例​

戦略オンラインリクエスト​

環境レベル構成の配信​

ユーザーレベル構成の配信​

戦略の一時的な無効化リクエスト​

戦略オフラインリクエスト​

2.3 Webhook チャネルのResponse​

2.4 リクエストの認証​

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

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