Webhook 通道接入文档

最近更新 2026/10/05

1. 简介

AE运营模块的 Webhook通道 定义了一种 API，其目的是在于连接下游客户方任何消息或类消息系统。客户经过较为轻量的 REST API 对接开发，即可快速支持非AE运营模块内置的触发通道。具体的调用链路参考下图：

首先AE运营模块（Engage）使用AE平台的事件数据和用户数据，进行目标人群的计算。
结合目标人群，并且组装好消息的内容。AE运营模块会分批发 HTTP 请求到您配置的一个 webhook 通道服务。
您自身的webhook通道服务接收到http的调用，获取到请求内容之后，可自行做格式转化、拼接其他业务数据，入异步处理队列等操作，并最终调用其他任何内部或外部的消息/类消息系统，可能调用的系统举例：

游戏邮件系统
游戏公告系统
封号系统
短信系统
第三方推送系统

处理完成之后（不包括异步处理流程），按照约定格式返回本次请求的处理结果，如果有处理失败的数据，需要明确返回该数据的序号和失败原因。AE运营模块会记录处理失败的数据。
回执事件数据回收（可选）

如果推送到游戏的邮件系统，那么可以在用户打开游戏邮件时埋点，把“点击邮件”作为一个点击推送的埋点事件，并且按照约定带上相关透传参数，以便实现更精准的触达环节的漏斗分析。

2. Webhook 通道服务

为与 AE 运营模块的 Webhook 通道对接，您需要开发一个 HTTP Endpoint Server。其应遵循的 API 定义见下文。

2.1 入参出参格式定义

Webhook 通道 Request

服务的入参，由AE运营模块构造生成，采用POST方式，Content-Type 设定为 application/json。请求体request_body 是一个 JSONArray，支持一批次发送多条消息数据。每条消息数据，代表给一个用户发送一个特定内容的消息。

提示

注意，AE运营模块的 Webhook通道在一个请求体中包含了多个用户的触发消息，这个是为了方便下游方便批量处理，从而提升发送的效率。一个批次包含多少个用户，支持自定义配置。

参数示例如下：

// 请求入参格式
[
    {"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", //对应一个运营任务，仅使用运营任务推送时携带
        "ops_task_instance_id": "0050_2023-01-01",  //对应一次运营任务实例，仅使用运营任务推送时携带
        "ops_task_exec_detail_id": "17795",  //对应一次任务实例的推送，仅使用运营任务推送时携带
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", //对应一次推送中的一次batch请求，同一次请求里的所有ops_request_id都是相同的，并且请求重试时此ID不会变化，客户业务系统如果要对请求做幂等校验，可用这个字段。仅使用运营任务推送时携带。
        "ops_exp_group_id": "122", //对应运营任务AB实验分组id，仅使用运营任务开启AB实验时携带
        "ops_flow_id":"0050", //对应一个流程画布，仅流程画布动作节点下发时携带
        "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 通道服务器发送 500 次请求。
发送批大小	[1,500]	100	表示一次调用参数的JsonArray里包含多少个元素。批次大小设置大，可以提高消息发送的效率；批次大小设置小，发送速度会比较慢，但是可靠性会更高。推荐设置为 100，最大可设置 500。
超时时间	[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运营模块认为本次调用失败。

4. 通道配置页面示例

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

参数	说明	备注
通道名称	Webhook 通道的名称（用于显示、选择）	唯一性校验
URL	接收消息推送的接口地址	支持同一个URL地址配置多个通道
发送ID	接收消息的目标用户ID类型，比如发送邮件用到的是用户的角色ID(role_id)	发送ID需要作为用户属性上报在目标用户人数预估时会过滤发送ID为空的用户
自定义请求头	发送请求时附加的自定义 HTTP 请求头，用于传递 Authorization、API Key 或业务标识	默认关闭，可按需开启；最多 10 个，Header 名称忽略大小写
通道鉴权	自定义通道鉴权方式	默认关闭，可按需开启
触达漏斗设置	漏斗步骤关联的元事件名	可选开启
内容模板	该通道发给用户的具体内容的模板，支持文本、动态文本、数值和对象组等字段类型，如发送邮件通道可以通过对象组类型配置道具内容（道具ID和道具数量），在触达任务前端页面展示出来，供配置运营任务的的运营人员填写	字段：参数的名称，发送时消息体使用显示名称：在创建任务的时候展示的字段输入方式：文本、动态文本、数值、单选下拉、日期、时间、对象组默认值：可选，选择输入方式后填写提示文案：在创建任务的时候输入框提示（非必填）必填：勾选后为必填，默认不勾选
自定义参数	根据通道要求选择性添加，该参数为透传	非必填字段：参数的名称，发送时消息体使用关联字段：字段关联的用户属性，发送消息体时字段值使用该属性值默认值：可选，已设置默认值，当属性值为空时使用默认值；未设置默认值，属性值为空时返回空值

5. 采集点击推送事件

通过 Webhook 通道推送的消息可以按需在客户端/服务端采集点击事件，采集方式可参考 ThinkingAI 数据接入手册中的上报事件的方式，事件名可以自定义，事件数据需要获取 Webhook 通道下发消息中的 #ops_receipt_properties 字段并且整体作为一个对象属性上报即可。如果有其他分析场景，此事件中也可以加上其他字段属性。注意：属性字段名一定是#ops_receipt_properties，类型是对象，不可随意更改。改了字段名，修改了字段内部的内容或者误把字段作为一个文本属性上报，都会导致后续数据使用异常代码示例：

JSONObject properties = new JSONObject();
//从 Webhook通道下发的message消息体中获取到json结构的ops_receipt_properties对象，整体作为一个对象属性上报
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. 采集点击推送事件​