目录
此内容是否有帮助?

# Webhook通道接入文档

# 简介

TE运营模块的 Webhook通道 定义了一种 API，其目的是在于连接下游客户方任何消息或类消息系统。

客户经过较为轻量的 REST API 对接开发，即可快速支持非TE运营模块内置的触发通道。

具体的调用链路参考下图：

  1. 首先TE运营模块（Engage）会读分析模块（Analytics）事件数据和用户数据，进行目标人群的计算。
  2. 结合目标人群，并且组装好消息的内容。TE运营模块会分批发 HTTP 请求到您配置的一个webhook服务。
  3. 您自身的webhook服务接收到http的调用，获取到请求内容之后，可自行做格式转化、拼接其他业务数据，入异步处理队列 等操作，并最终调用其他任何内部或外部的消息/类消息系统，可能调用的系统举例：
  • 游戏邮件系统
  • 游戏公告系统
  • 封号系统
  • 短信系统
  • 第三方推送系统
  1. 处理完成之后（不包括异步处理流程），按照约定格式返回本次请求的处理结果，如果有处理失败的数据，需要明确返回该数据的序号和失败原因。TE运营模块会记录处理失败的数据。
  2. 回执事件数据回收（可选）
  • 如果推送到游戏的邮件系统，那么可以在用户打开游戏邮件时埋点，把“点击邮件”作为一个点击推送的埋点事件，并且按照约定带上相关透传参数，以便实现更精准的触达环节的漏斗分析。

# Webhook服务

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

# 入参出参格式定义

# Webhook Request

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

参数示例如下：

// 请求入参格式
[
    {"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。由运营在在'TE运营模块-通道管理'侧定义
    "push_id": "accountid123987001",
    
    //模板参数，此参数下的具体参数内容可以在'TE运营模块-通道管理'侧定义
    "params": {
        "title": "每日活动",
        "content": "你好张三，快来参加活动吧！",
        //对象组
        "attachment": [
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        ]
    },
    //自定义参数,可以带出用户属性，此参数下的具体参数内容可以在'TE运营模块-通道管理'侧定义
     "custom_params": {
         "gameuid":"123acb001",
         "name": "张三"
    },
    //通道回执属性,此参数由TE运营模块系统默认添加，用于后续数据统计，通常业务侧无需解析，透传到下游即可。下游上报时注意把这个json对象直接上报，不要toString之后再上报
    "#ops_receipt_properties": {   
        "ops_project_id": 1  //对应TE项目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不会变化，客户业务系统如果要对请求做幂等校验，可用这个字段。
    }
}
参数名 参数类型 是否必填 参数描述 备注
push_id
 String
 是
 推送ID
 具体参数字段可以在'TE运营模块-通道管理-推送ID'侧定义
params
 Object
 否
 模板参数
 需要在推送时候由运营填写的一些通道参数，比如推送的内容。
具体参数内容可以在'TE运营模块-通道管理-模板参数'侧定义
custom_params
 Object
 否
 自定义参数
 需要由系统自动带出的推送目标用户的用户属性
具体参数内容可以在'TE运营模块-通道管理-自定义参数'侧定义
#ops_receipt_properties
 Object
 是
 TE运营模块回执字段
 TE运营模块系统默认添加
下游系统如果需要观测消息的点击情况，则需要在点击事件中直接透传上报此字段在任务目标设置的转化事件中，无需上报此字段

模板参数，自定义参数的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里返回给数数。这会让任务的触发成功指标统计更加准确。
失败列表里的对象index属性代表序号，编号从1开始，不是从0开始！message字段不是必填，但是强烈建议返回，便于异常时候的问题排查
假如return_code=1，无论data.fail_list里传了什么，都认为全部失败。

# 请求鉴权

鉴权功能默认不开启。如果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);
}

# 请求并发性能

为了保证消息推送速度，webhook服务支持的并发越高越好，建议可以支持100以上TPS。同时，数数的智能运营模块可以按照下游webhook服务的并发能力上限，进行相应的限流配置。

# 请求和结果完整测试例子

// 请求信息
curl -X POST "http://localhost:8999/v1/webhook/test/sample" 
-H "accept: */*" 
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Type: application/json" 
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"costom_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"
}

# Webhook 通道可配置参数介绍

以下参数默认后台配置，如需修改可联系数数科技客户成功

配置项
 可选值
 默认值
 配置描述
发送限流
 -1，[1,10000]
 不限流
 单位：次/秒
设置为-1，代表不限流
设置为1-10000的数字，例如500，代表每秒钟最多接受请求500次下游webhook服务器
发送批大小
 [1,500]
 100
 表示一次调用参数的JsonArray里包含多少个元素
批次大小设置大，可以提高消息发送的效率
批次大小设置小，发送速度会比较慢，但是可靠性会更高
推荐设置为100，最大可设置500。
超时时间
 [0,600]
 60
 单位：秒
http请求socket超时时间，默认是60s
如果设置了<=0，相当于不超时
失败重试次数
 [0,10]
 0
 为了避免业务上重复推送，默认0次，即不重试
如果配置了>0的值，当接口超时或者接口返回return_code!=0会走重试逻辑
失败重试时间间隔
 [0,600]
 5
 单位：秒
默认每隔5s重试一次
返回值强校验
 开启，不开启
 开启
 开启后，TE运营模块服务会校验下游服务器返回的response的格式，如果不符合上面webhook response参数定义规范认为失败
例子：假设超时时间设置为5s
如果不开启返回值强校验，webhook服务在5s内正常返回，且返回值HTTP 200 无 Body，TE运营模块认为本次调用成功
如果开启返回值强校验，webhook服务在5s内正常返回，且返回值HTTP 200 无 Body或者Body格式和约定的规范不一致，TE运营模块认为本次调用失败

# 通道配置页面示例

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

# 采集点击推送事件

通过webhook通道推送的消息可以按需在客户端/服务端采集点击事件，采集方式可参考数数数据接入手册中的上报事件的方式，事件名可以自定义，事件数据需要获取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);

← 预置App推送接入文档 →