生活服务消息推送

我的收藏

用户在抖音生活服务内的数据变更时，可通过 webhook 的方式将消息推送给开发者，开发者可以根据需要订阅不同消息。消息仅包含基本的信息，如需要查询详细数据，可在收到消息后主动调用相关接口获取明细数据。

申请流程

1、完成开发者入驻。

2、申请开通对应接口能力并完成审批，不同消息需申请对应的不同能力，各类消息所需能力详见各消息内容。申请路径：抖音服务商平台或抖音开发者平台>控制台>应用详情>解决方案>查看详情>选择对应能力申请开通

3、建立与商家的授权关系。

4、配置路径：抖音服务商平台或抖音开发者平台>控制台>应用详情>开发配置>Webhooks

首次对接webhook需要添加接收消息的URL，每个应用共用一个URL，配置一次即可

如需修改也是在同样的位置点击修改

注意事项：

•

目前仅支持同一个应用配置一个接收消息地址，开发者需根据event字段区分消息类型对content内容进行不同的处理。

•

前三步参考文档技术服务商接入指南和自研开发者接入指南。

•

第四步提供的消息地址需满足抖音侧请求验证功能，才能配置成功。

抖音侧发送的 POST 验证请求示例如下：

说明
注：验证用的content 不是 string类型，而是object

{
  "event": "verify_webhook",
  "client_key": "",
  "content": {
    "challenge": 12345
  }
}

当开发者收到抖音的验证请求时，需要解析出 challenge 值，并立即返回该 challenge 值作为响应。需要注意，返回内容需要放入响应的 Body 里，不能直接返回；并且返回内容为 text 格式的 json 数据。响应示例如下：

{
  "challenge": 12345
}

推送内容

HTTP method

POST

请求头字段

字段	说明
Msg-Id	同一实体下同一action的msg_id相同，服务商可根据msg_id对于消息去重
X-Douyin-Signature	抖音侧签名，服务商可根据签名判断该消息是否来自抖音开放平台
Content-Type	固定值application/json

注意：消息可能重复推送，请使用 Msg_Id 进行去重处理！

请求体字段

字段	类型	说明
event	string	消息类型，用于区分各类消息
client_key	string	对应服务商平台或开发者平台中的APPID，应用ID
from_user_id	string	标识用户身份的openId，同一用户在不同的APPID中openId不相同
content	string	消息内容，根据需要解析消息内容，不同类型的消息内容不同
log_id	string	抖音内部日志id，可提供给抖音方便排查问题

请求体示例

{
  "event": "life_trade_order_notify",
  "client_key": "axxxxxxxxxxxxx",
  "from_user_id": "f6e35c98-1e53-4943-ad6d-f476f869deab",
  "content": "{\"action\": \"pay_success\",\"msg_time\": 1665991178,\"order\": {\"order_id\": \"123\",\"pay_amount\": 1,  \"original_amount\": 1, \"account_id\": \"123\",\"create_time\": 1665991178,\"pay_time\": 1665991178}}",
  "log_id": "202210101930530102281180650970B5AF"
}

验签方式

用户可通过请求头中的 X-Douyin-Signature 字段判断该消息是否来自抖音开放平台。抖音服务端会将应用的 AppSecret 和消息体使用 sha1 哈希作为 X-Douyin-Signature 的 value。开发者可以自行使用 AppSecret 和收到的消息体进行 sha1 哈希，与该请求头进行比对，确认消息推送请求来自抖音。

java 版验签 demo

import org.apache.commons.codec.digest.DigestUtils; // sha1算法库


        // 获取消息中body
        String str, wholeStr = "";
        try{
            BufferedReader br = re.getReader();
            while((str = br.readLine()) != null){
                wholeStr += str;
            }
        } catch (Exception e){
            log.warn("获取请求内容失败");
        }
        // 获取请求头中的加签信息
        String  signature = re.getHeader("X-Douyin-Signature");
        String data = appSecret + wholeStr;
        String sign = DigestUtils.sha1Hex(data);
        if(!sign.equals(signature)){
            log.error("验签失败");
        }

响应参数

响应内容可以为空。

开发者收到消息推送后，http code 响应 200 且响应时间小于 3s，抖音侧即认为推送成功。

若开发者 http 响应 code 非 200 或响应时间超过 3s，抖音侧会间隔 500ms 发起重试，最大重试次数为 3 次。

抖音侧收到成功请求时也可能会继续重复推送，请务必使用请求头中 Msg-Id 进行消息去重处理。