Webhook config integration guide

Last updated 10/03/2026

1. Introduction

The Webhook channel of Config Center establishes a connection mechanism for interactive communication with external systems or other internal modules. Through Webhook, Config Center can send specific data to a designated receiver. After processing the data accordingly, the receiver can synchronize with Config Center data, perform specific operations, or further distribute the data.

2. Webhook channel service

2.1 Request and response format

Webhook channel request

• Request method: Constructed by Config Center and sent as a POST request
• Content - Type: Set to application/json
• Request body structure: The request body request_body is a JSONArray, so multiple messages can be sent in one batch. Each message relates to a specific Config Item
• Request format: The default request parameter format is as follows

[{
    "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}
}]

The parameter names above can be customized. To adjust them, contact ThinkingAI after-sales support

Parameter name	Parameter type	Description	Remarks
opType	String	${opTypeValue} is a placeholder (the same applies below). The default values are online, suspend, offline, which correspond to the go-online (including going online again after editing), suspend, and take-offline actions in the UI.	When a strategy goes offline on expiration, no offline notification is sent by default. To enable it, contact ThinkingAI after-sales support.
configId	String	The config item ID identifies an integrated business module	For details about config items, see Config items
templateId	String	The template ID identifies the specific form of a business feature.	For details about templates, see Config templates
strategyId	String	The strategy ID is the unique ID of a config strategy and is used to manage the strategy's full lifecycle.	For details about strategies, see Config strategies
targetType	String	Valid values of targetType are all/targetEnv/targetAudience, which correspond to all, environment-level configuration, and user-level configuration.	For an introduction to target environments and target users, see the Targeting section of Config strategies
systemId (optional)	JSON	When Config Center connects to multiple downstream systems, you can enable the System ID. Once it is enabled, online requests for user-level configurations are split by the value of the System ID field and delivered separately; for suspend or offline actions, the request also carries the complete list of target system values. This makes relaying easier for the webhook service.	For how to set the System ID, see Config Center Channel Settings
targetEnv	JSON	The target environment conditions configured in the UI, which the webhook server needs to parse. For an example of the environment condition format, see Strategy online request in 2.2. Multiple conditions are combined with AND logic.	Not included in suspend and offline requests
targetAudience	JSONArray	The target user list. For user information, add User Properties as custom parameters in the Webhook channel. For details, see the User Parameters section in Config Center Channel Settings.	Not included in suspend and offline requests
configParams	JSON	The specific parameter content configured with the config template.	Not included in suspend and offline requests
#ops_receipt_properties	JSON	A passthrough parameter used for automatic strategy analysis. You don't need to process it for now.	Added by the AE Engage module by default
isEndPush	Boolean	Indicates whether this push has ended. Sent only when user-level configuration delivery is complete.

Note: In the targetAudience and configParams parameters, data of all types (such as integers, decimals, and dates) is sent as the String type in requests.

2.2 Examples

Strategy online request

Environment-level configuration delivery

The following example uses "serverId" as the environment condition

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "targetType": "targetEnv",
    "syetemId": {   // This parameter is sent only when the System ID is enabled
        "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"
    }
}]

User-level configuration delivery

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121002"
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "targetType": "targetAudience",
    "syetemId": { // This parameter exists only when the System ID is enabled. User packages are split and delivered by System ID value
        "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"
    }
}]

After the System ID is enabled, when you edit a strategy and publish a new version online, a strategy change notification is sent to all systems the strategy has covered before the online request, so that downstream systems can process historical data. This notification is sent only when the System ID is enabled.

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121002"
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "targetType": "targetAudience",
    "syetemId": {    // List of system values the strategy has covered
        "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"
    }
}]

By default, a strategy going online is pushed in batches. The following is the push completion flag.

[{
    "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"
    }
}]

Strategy suspend request

[{
    "opType": "suspend",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "syetemId": {  // This parameter exists only when the System ID is enabled
        "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"
    }
}]

Strategy offline request

[{
    "opType": "offline",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "syetemId": {  // This parameter exists only when the System ID is enabled
        "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 channel response

Respond to requests in the following parameter format.

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // Each element in fail_list contains information about a failed object, including the error message and the sequence number of the failed object. Sequence numbers start from 1. For example, if 5 objects are sent with sequence numbers 1-5, 3 succeed and 2 fail, and the 2nd and 4th fail, the following is returned
        "fail_list": [{
            "index": 2,
            "message": "system error"
        }, {
            "index": 4,
            "message": "push id not found"
        }]
    }
}

Parameter name	Parameter type	Required	Parameter description
return_code	Integer	Yes	Return code 0 means success (or partial success) 1 means failure
return_message	String	No	Return message
data	Object	No	Returned data
data.fail_list	Array	No	If return_code=0: If data.fail_list is [] or null, all objects are considered successful If data.fail_list is not empty, the push partially failed, and the failure details are as defined in the list. If partial failure never occurs in your business, just pass []; Note: We recommend that you perform pre-validation in the API processing logic so that failed objects are listed in fail_list and returned to AE. This makes the task's push success metrics more accurate. The index property of objects in the failure list is the sequence number, which starts from 1, not 0! The message field is not required, but we strongly recommend returning it to make troubleshooting easier when exceptions occur If return_code=1, all objects are considered failed regardless of what is passed in data.fail_list.

2.4 Request authentication

After this step is configured, you can enable it on the Webhook channel page in the product.

Authentication is disabled by default. If the Webhook channel server doesn't require authentication, skip this section.

To support authentication, turn on the authentication switch when you configure the channel. The sender adds the signature to the HTTP request header with the key X-AE-OPS-Signature. The server needs to generate a signature by signing the Request Body with the secret key using HmacSHA1, and then compare it with the sender's signature. If they match, authentication succeeds.

Reference Java implementation of the signature algorithm:

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
   HmacSHA1 signature algorithm
   
   secretKey is the secret key configured by the customer
   requestBody is the JSONString of the request content
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
    String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody);
    return signature;
}

Reference PHP implementation of the signature algorithm:

/**
 * HmacSHA1 signature algorithm
 * @param $secretKey : Secret key configured by the customer
 * @param $requestBody : JSONString of the request content
 * @return string Signature value
 */
function HmacSHA1($secretKey, $requestBody) {
    return hash_hmac('sha1', $requestBody, $secretKey);
}

2.5 Request concurrency performance

To ensure message push speed, the higher the concurrency the Webhook channel service supports, the better. We recommend supporting more than 100 TPS. In addition, the Engage module of AE supports push rate limiting, which you can adjust according to the maximum concurrency of the downstream Webhook channel service.

3. Configurable parameters of the Webhook channel

The following parameters are configured in the backend by default. To modify them, contact ThinkingAI after-sales support

Config items	Valid values	Default value	Description
Dedicated host nodes for Config Center	Specific hosts	None	Not isolated by default. To isolate, configure multiple nodes separated by commas. Example: ta4,ta5
Config Center webhook request format	Specific JSON	None	For the default format template, see the examples above. If you plan to connect to an existing API and don't need to distinguish users who were pushed successfully, you can customize the request format template to connect to the existing service directly without development.
Send "publish ended" status notification	Enabled, Disabled	Enabled	When an online push to target users includes a large number of users, it is split into packages and pushed to the Webhook server. The server can use this request to determine when the push is complete.
Send request on automatic offline	Enabled, Disabled	Disabled	When a strategy automatically goes offline at the set time, no offline request is sent to the Webhook server by default. After this is enabled, automatic offline also sends an offline request, in the same format as manual offline.
Config item delivery command types	3 types, 5 types	3 types	Three types by default: online, offline, suspend. Can be configured to distinguish going online after editing (re_online) and forced offline (force_offline).
Send rate limit	-1，[1,10000]	Unlimited	Unit: requests/second. -1 means no rate limit. A number from 1 to 10000, such as 500, means that at most 500 requests per second are sent to the downstream Webhook channel server.
Send batch size	[1,5000]	1000	The number of elements in the JsonArray of the parameters in one call A larger batch size improves message sending efficiency A smaller batch size makes sending slower but more reliable We recommend 1000. The maximum is 5000
Timeout	[0,3600]	60	Unit: seconds Socket timeout of HTTP requests. The default is 60s If set to <=0, there is no timeout
Failure retries	[0,10]	0	To avoid duplicate pushes, the default is 0, meaning no retry If a value >0 is configured, the retry logic runs when the API times out or returns return_code!=0
Retry interval on failure	[0,600]	5	Unit: seconds Retries every 5s by default
Strict response validation	Enabled, Disabled	Enabled	After this is enabled, the AE Engage module validates the format of the response returned by the downstream server. If it doesn't conform to the Webhook channel response parameter specification above, the call is considered failed Example: assume the timeout is set to 5s If strict response validation is disabled, and the Webhook channel service returns normally within 5s with HTTP 200 and no body, the AE Engage module considers the call successful If strict response validation is enabled, and the Webhook channel service returns normally within 5s with HTTP 200 and no body, or the body format is inconsistent with the agreed specification, the AE Engage module considers the call failed