WebHooks接入

我的收藏

webhook由抖音提供接口定义，服务商在开放平台注册回调地址，抖音调服务商异步通知。消息仅包含基本的信息，如需要查询详细数据，可在收到消息后主动调用相关接口获取明细数据。

注意：webhook通知为异步通知，抖音不保证消息必达、有序、不重复。请开发者自行根据消息唯一键去重。

场景和接口

在对接的解决方案、能力文档中查看需要接入的 WebHooks 接口。

消息推送回调接口说明

仅支持https协议。

HTTP method

POST

请求头字段

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

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

请求体字段

通用请求体字段如下，其中content为具体的接口业务内容（json格式），具体内容需要参考回调接口的文档说明

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

请求体示例

{
  "event": "life_trade_order_notify",
  "client_key": "axxxxxxxxxxxxx",
  "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 哈希，与该请求头进行比对，确认消息推送请求来自抖音。

Go版验签Demo

import (                                                                                                                                                                                                                       
        "bufio"                                                                                                                                                                                                                    
        "bytes"                                                                                                                                                                                                                    
        "crypto/sha1"                                                                                                                                                                                                              
        "encoding/hex"                                                                                                                                                                                                             
        "fmt"                                                                                                                                                                                                                      
        "io"                                                                                                                                                                                                                       
        "net/HTTP"                                                                                                                                                                                                                 
        "strings"                                                                                                                                                                                                                  
    )                                                                                                                                                                                                                              
                                                                                                                                                                                                                                   
    func VerifyJavaStyleSignature(r *HTTP.Request, appSecret string) bool {                                                                                                                                                        
        var wholeStr string                                                                                                                                                                                                        
        if r.Body != nil {                                                                                                                                                                                                         
            var bodyBytes []byte                                                                                                                                                                                                   
            if data, err := io.ReadAll(r.Body); err == nil {                                                                                                                                                                       
                bodyBytes = data                                                                                                                                                                                                   
            }                                                                                                                                                                                                                      
            r.Body = io.NopCloser(bytes.NewReader(bodyBytes))                                                                                                                                                                                                                                                                                                                                                                                         
            scanner := bufio.NewScanner(bytes.NewReader(bodyBytes))                                                                                                                                                                
            var sb strings.Builder                                                                                                                                                                                                 
            for scanner.Scan() {                                                                                                                                                                                                   
                sb.WriteString(scanner.Text())                                                                                                                                             
            }                                                                                                                                                                                                                      
            wholeStr = sb.String()                                                                                                                                                                                                 
        }                                                                                                                                                                                                                             
        signature := r.Header.Get("X-Douyin-Signature")                                                                                                                                                                                                                                                                                                                                                                                                   
        data := appSecret + wholeStr                                                                                                                                                                                                                                                                                                                                                                                                                   
        h := sha1.New()                                                                                                                                                                                                            
        h.Write([]byte(data))                                                                                                                                                                                                      
        sign := hex.EncodeToString(h.Sum(nil))                                                                                                                                                                                     
                                                                                                                                                                                                                                   
        if sign != signature {                                                                                                                                                                                                     
            fmt.Println("验签失败")                                                                                                                                                                                                
            return false                                                                                                                                                                                                           
        }                                                                                                                                                                                                                          
        return true                                                                                                                                                                                                                
    }

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("验签失败");
        }

NodeJS版验签Demo

const crypto = require('crypto');                                                                                                                                                                                              
                                                                                                                                                                                                                                                                                                                                                                                                                                                            
    function verifyJavaStyleSignature(req, appSecret) {                                                                                                                                                                            
        let wholeStr = "";                                                                                                                                                                                                                          
        if (req.body) {  
            const bodyStr = req.body.toString();                                                                                                                                              
            wholeStr = bodyStr.split(/\r?\n/).join('');                                                                                                                                                                            
        }                                                                                                                                                                                                                          
                                                                                                                                                                                                        
        const signature = req.headers['X-Douyin-Signature'];                                                                                                                                                                                                                                                                                                                                                                              
        const data = appSecret + wholeStr;                                                                                                                                                                                         
        const sign = crypto.createHash('sha1').update(data).digest('hex');                                                                                                                                                         
                                                                                                                                                                                                                                   
        if (sign !== signature) {                                                                                                                                                                                                  
            console.error("验签失败");                                                                                                                                                                                             
            return false;                                                                                                                                                                                                          
        }                                                                                                                                                                                                                          
        return true;                                                                                                                                                                                                               
    }

加密字段解密

对请求参数中的加密字段，若需进行解密，参考文档：加密字段解密

响应体

响应内容可以为空。

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

若开发者 HTTP 响应 code 非 200 或响应时间超过 2.5s，抖音侧会间隔发起重试，区分接口做最多N次重试。

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

错误码

需参考具体回调接口的文档说明

消息推送内容说明

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

接入流程

接入前置条件

注：以下三步参考文档：

技术服务商：技术服务商入驻指南_生活服务商家应用_抖音开放平台

自研商家：自研商家入驻指南_生活服务商家应用_抖音开放平台。

完成开发者入驻。

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

建立与商家的授权关系。

配置回调步骤

回调地址配置

第一种方式：若为接入中的应用，操作路径如下：

注：接入中的应用，修改也同此操作路径

第一步：在解决方案接入详情页左侧导航栏选中基础配置-Webhooks配置。

第二步：点击页面中配置请求网址 URL 模块中的配置按钮，填写你要配置的请求网址，完成后点击确定按钮保存。

第二种方式：若非接入中的应用，操作路径如下：

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

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

回调地址验证

完成请求网址编辑后，点击保存时，开放平台会向你配置的网址推送一个 application/json 格式的 POST 请求, 该请求用于验证你配置的网址的合法性。通过开放平台验证的请求网址才能配置成功，请求网址配置成功后，你才可以进一步订阅你的应用关心的事件。

开放平台发送的 POST 验证请求示例如下：

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

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

当开发者收到抖音的验证请求时，需要解析出 challenge 值，并立即返回该 challenge 值作为响应。

注意
返回内容需要放入 ResponseBody 里，不能直接返回，需要返回内容为 text 格式的 JSON 数据。

响应示例如下：

{
  "challenge": 12345
}

事件订阅

开发者可通过页面中订阅事件模块订阅需要通知的事件。

说明
如果开发者服务器长时间未响应事件推送请求，可能会取消开发者的订阅状态，开发者需重新订阅。

地址配置要求

目前仅支持同一个应用配置一个接收消息地址，首次对接webhook需要添加接收消息的URL，每个应用共用一个URL，配置一次即可；

输入的回调地址必须以 https:// 开头；

开发者需根据event字段区分消息类型对content内容进行不同的处理。

常见问题

问题	建议方案
webhook配置URL报错/不通过	1.地址与协议是否合规：仅支持 https，统一POST 且Content-Type为 application/json； 2.确认配置的url的连通性，是否可正常访问 3.确认响应给抖音的body是否为json格式，除此之外验证用的content不是string类型，而是object，其他类型会报错参数不合法
没有配置webhooks的相关事件订阅按钮	1.检查回调地址是否配置：订阅事件前提是需要先配置请求网址 URL，先根据【配置回调步骤】完成配置，且url验证通过，之后才可订阅事件 2.若新建的应用没有配置 Webhooks 的相关事件订阅按钮，可以按照以下步骤解决：应用先申请相关订阅的解决方案应用权限，比如商品消息通知webhook，就要应用有商品相关接口的权限，申请之后就可能会出现事件订阅按钮。
事件也订阅了，但未收到通知	1.同一应用只能配置一个接收消息地址，需要根据事件类型做不同的业务处理，请先检查是没有收到请求还是收到请求但未正确处理 2.订阅后若长时间未响应会被取消，需重新订阅，请检查当前的订阅状态 3.消息积压，会出现推送延迟情况，这种情况可以耐心等待一段时间再看下，如长时间未收到可以进线抖音技术反馈;
重复收到推送了	重复推送的情况： 1.开发者收到消息推送后，若开发者 HTTP 响应 code 非 200 或响应时间超过 2.5s，抖音侧会间隔发起重试，区分接口做最多N次重试。 2.抖音侧收到成功请求时也可能会继续重复推送，webhook通知为异步通知，抖音不保证消息必达、有序、不重复请务必使用请求头中 Msg-Id 进行消息去重处理