跳到主要内容

Webhook 配置接入文档

最近更新 2026/10/03

1. 简介​

配置中心的 Webhook 通道旨在建立一种连接机制，用于与外部系统或内部其他模块进行交互通信。通过Webhook，配置中心能够将特定的数据发送到指定的接收端，接收端经过相应的处理后，可以实现与配置中心数据的同步、执行特定操作或进行数据的进一步分发等功能。

2. Webhook通道服务​

2.1 入参出参格式定义​

Webhook 通道 Request​

  • 入参方式：由配置中心构造生成，采用 POST 方式发送请求
  • Content - Type：设定为 application/json
  • 请求体结构：请求体 request_body 是一个 JSONArray，支持一批次发送多条消息数据。每条消息数据代表与一个特定 配置项 相关的消息
  • 入参请求格式：默认请求参数格式如下
[{
    "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 用于识别接入的一个业务模块配置项相关说明见 配置项管理
templateId字符串模板 ID 用于识别具体的业务功能形式。模板相关说明见 配置模板管理
strategyId字符串策略 ID 为配置策略的唯一 ID，用于策略的全生命周期管理。策略相关说明见 配置策略管理
targetType字符串targetType 可取值 all/targetEnv/targetAudience，对应全部、环境级配置、用户级配置。关于目标环境、目标用户的介绍，见 配置策略管理的目标受众部分

systemId (可选)

JSON

通过配置中心对接多下游系统时，可启用系统对接标识。开启后，用户级配置下发上线请求将根据系统对接标识字段值拆包下发；操作暂停或下线，请求中也将携带完整的目标系统取值。方便webhook服务做中转处理。

设置系统对接标识见 配置通道设置

targetEnvJSON前台配置的目标环境条件，需 webhook server 解析处理，环境条件格式示例见 2.2 中 策略上线请求。多条件间为 且 关系。

下发暂停生效和下线请求时不携带该参数

targetAudience

JSONArray

目标用户列表。用户信息需在 Webhook 通道中添加 用户属性 作为自定义参数，见 配置通道设置 中「用户参数」部分。

下发暂停生效和下线请求时不携带该参数

configParamsJSON使用配置模板配置的具体参数内容。下发暂停生效和下线请求时不携带该参数
#ops_receipt_propertiesJSON透传参数，用于策略自动分析，暂时无需处理。AE 运营模块系统默认添加
isEndPush布尔本次推送是否结束标识，仅在用户级配置下发完成时下发。

注意：在 targetAudience 和 configParams 的参数中，对于所有类型的数据(如整数，小数，日期等类型)，在发送请求时，都将以 “字符串” 类型进行发送。

2.2 示例​

策略上线请求​

环境级配置下发​

以 “serverId” 为环境条件为例

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "targetType": "targetEnv",
    "syetemId": {   // 仅开启系统对接标识时下发此参数
        "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": { // 仅开启系统对接标识有此参数，按照系统对接标识取值拆用户包下发
        "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"
    }
}]

开启系统对接标识后，当编辑策略发布新版本上线时，在上线请求前会先下发策略变更通知至所有该策略覆盖过的系统，用于下游历史数据处理。仅启用系统对接标识后有此通知。

[{
    "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": {  // 仅开启系统对接标识有此参数
        "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": {  // 仅开启系统对接标识有此参数
        "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_codeInteger是

返回码

0 代表成功（或者部分成功）

1 代表失败

return_messageString否返回信息
dataObject否返回数据

data.fail_list

Array

否

假如 return_code=0，

  • data.fail_list为 [] 或 null 时，会认为全部成功
  • data.fail_list 不为空，则为部分失败，失败的明细为 list里定义的。
  • 如果业务上不存在部分失败的情况，直接传 [] 就行；

注意：

  1. 建议在接口处理逻辑里面做前置校验，以便在fail_list 里返回给 AE。这会让任务的推送成功指标统计更加准确。
  2. 失败列表里的对象 index 属性代表序号，编号从 1 开始，不是从 0 开始！
  3. 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无默认格式模板见上方示例。若计划接入已存在接口，且不需要区分推送成功用户的场景时，可定制请求格式模板，来达到无需开发，直接接入现有服务的目的。

发送“一次发布结束”状态通知

开启，不开启开启当目标用户类型的上线推送，包含的用户人数较多时，会拆包推送到 Webhook 服务端，服务端需要判断此次推送完成时，可根据此请求判断。

自动下线是否下发请求

开启，不开启不开启策略按设定的时间自动下线时，默认不会发送下线请求到 Webhook 服务端。开启后，自动下线也会发送下线请求，格式与手动下线相同。

配置项下发命令类型

3种，5种

3种

默认为 online、offline、suspend 三种，可配置为区分编辑上线（re_online）和强制下线（force_offline）。

发送限流

-1，[1,10000]

不限流

单位：次/秒；设置为 -1，代表不限流；设置为 1-10000 的数字，例如 500，代表每秒最多向下游 Webhook 通道服务器发送 500 次请求。
发送批大小

[1,5000]

1000

表示一次调用参数的JsonArray里包含多少个元素

批次大小设置大，可以提高消息发送的效率

批次大小设置小，发送速度会比较慢，但是可靠性会更高

推荐设置为 1000，最大可设置 5000

超时时间

[0,3600]

60

单位：秒

http 请求 socket 超时时间，默认是 60s

如果设置了<=0，相当于不超时

失败重试次数[0,10]0

为了避免业务上重复推送，默认0次，即不重试

如果配置了 >0 的值，当接口超时或者接口返回 return_code!=0 会走重试逻辑

失败重试时间间隔[0,600]5

单位：秒

默认每隔 5s 重试一次

返回值强校验开启，不开启开启

开启后，AE 运营模块服务会校验下游服务器返回的 response 的格式，如果不符合上面 Webhook 通道 response 参数定义规范认为失败

例子：假设超时时间设置为 5s

如果不开启返回值强校验，Webhook 通道服务在5s内正常返回，且返回值 HTTP 200 无 Body，AE 运营模块认为本次调用成功

如果开启返回值强校验，Webhook 通道服务在5s内正常返回，且返回值 HTTP 200 无 Body 或者 Body 格式和约定的规范不一致，AE 运营模块认为本次调用失败

这篇文档对你有帮助吗？
本页内容