设置 TikTok API for Business Webhook
TikTok 的 API for Business 为每个开发者应用和每种事件类型,向一个回调 URL 发送 Webhook。订阅时使用 POST /business/webhook/update/,并传入应用的 app_id 和 secret(应用密钥)。event_type 为 VIDEO 时订阅四种帖子发布事件,为 COMMENT 时订阅 comment.update。每次投递都是 HTTPS POST,在 Tiktok-Signature 请求头中携带签名,签名以应用密钥为键,由 HMAC-SHA256 计算而来。
easyCoexistence 为应用订阅 TikTok 的评论 Webhook,验证 TikTok 签名,并将每个评论事件转发到您为账户设置的 HTTPS 端点,使用其自有的签名密钥。
TikTok 在丢弃未收到 HTTP 200 响应的投递前,以指数退避方式重试的时长
单个 item_list 可指定的帖子 ID 数量上限,用于将 comment.update 事件限定在特定帖子上
TikTok 随每次投递发送的 webhook-schema-version 请求头的当前值
TikTok 参考文档中列出的 Webhook 配置端点,这些端点使用 app ID 与应用密钥进行身份验证
Tiktok-Signature 背后的算法:时间戳、点号和请求体拼接而成,以应用密钥为键,并以十六进制编码
订阅 comment.update 所需的应用权限位于 TikTok Accounts 之下,发布事件则需要 Business Content 权限
TikTok 账户应用可以接收哪些 Webhook 事件?
有两类事件,各自作为独立的 event_type 订阅。VIDEO 涵盖通过 /business/video/publish/ 或 /business/photo/publish/ 发布的帖子,COMMENT 涵盖账户的图文帖子和公开视频帖子上的评论,无论这些帖子是通过 API 还是 TikTok 应用发布的:
订阅之前,应用需要什么?
需要 API for Business 的访问权限、一个开发者应用,以及已授权该应用的 TikTok 账户。TikTok 的订阅指南为每个类别增加一项权限,而评论事件还需要每位所有者授予的一个权限范围:
- 发布事件:应用上的 TikTok Accounts 与 Business Content 权限。
- 评论事件:应用上的 TikTok Accounts 与 Business Comment 权限。
- comment.update:由所有者授予并保持有效的 comment.list 权限范围。
- 必须是 HTTPS 回调 URL,并能立即返回 HTTP 200。
如何订阅?
对每个 event_type 分别发送一次 POST 请求至 /business/webhook/update/。请求体包含 app_id、secret、event_type(VIDEO 或 COMMENT)和 callback_url;对于 COMMENT,还可以包含 item_list。响应会回显 app_id、event_type、callback_url,以及已配置时的 item_list。对同一 event_type 再次调用会替换回调 URL。
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "<APP_ID>",
"secret": "<APP_SECRET>",
"event_type": "COMMENT",
"callback_url": "https://hooks.example.com/tiktok/"
}'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": { "app_id": "<APP_ID>", "callback_url": "https://hooks.example.com/tiktok/", "event_type": "COMMENT" }
}item_list 如何限定评论事件?
它将 comment.update 限定在所指定的帖子上,最多可填 100 个来自 /business/video/list/ 的 ID,并且第一次列表决定此后应用的模式:
- 首次 COMMENT 调用带
item_list:仅投递列出的帖子的事件。 - 之后带
item_list的调用:新帖子会加入已列出的帖子。 - COMMENT 调用不带
item_list且之前未设置:投递的是授权该应用的账户的帖子事件。 - COMMENT 调用不带
item_list且列表已存在:已配置的帖子保持不变。
如何查看或取消订阅?
使用 app_id、secret 和 event_type 发送 GET 请求至 /business/webhook/list/,即可返回配置:仅当该事件类型存在回调 URL 时才会返回 callback_url,仅当设置过时才会返回 item_list。使用 app_id、secret 和 event_type 发送 POST 请求至 /business/webhook/delete/ 即可删除订阅;对于 COMMENT,若删除调用中包含 item_list,则只删除这些帖子的订阅,若不包含,则所有帖子的评论事件全部停止。
回调 URL 必须做什么?
立即应答。TikTok 以 JSON 形式通过 HTTPS 发送 POST 请求,除 HTTP 200 外的任何响应都视为投递失败,并以指数退避方式重试最长 72 小时,之后丢弃该事件。投递至少一次,因此同一事件可能到达两次,处理必须保证幂等。每个请求携带三个值得记录的请求头:tiktok-signature、webhook-schema-version 和 x-tt-logid,请求体包含 client_key、event、create_time(以秒为单位)、user_openid(即账户的 business_id)以及 content(序列化后的 JSON 字符串)。
如何验证 Tiktok-Signature?
将请求头按逗号拆分,再按等号拆分:t=<unix>,s=<hex>。用 t 的值、点号和请求体拼接出签名消息,以应用密钥为键计算其 HMAC-SHA256,进行十六进制编码后与 s 比较。然后检查 t 的时效:TikTok 对投递时间签名以防止重放,其示例接受的延迟为 5 秒。直接使用接收到的原始请求体,可避免重新序列化 JSON 时产生差异。
import hashlib, hmac, time
def verify_tiktok(raw_body: bytes, header: str, app_secret: str, max_age: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, s = parts.get("t", ""), parts.get("s", "")
if not t.isdigit():
return False
expected = hmac.new(app_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, s) and abs(time.time() - int(t)) <= max_age如何通过 easyCoexistence 接收 TikTok 事件?
为账户设置一个目标地址。easyCoexistence 为自己的应用订阅 COMMENT,验证 TikTok 的签名,立即应答 TikTok,并将已连接账户的每条 comment.update 以 POST 方式发送到为该账户设置的 HTTPS 端点。在 Claude 或 ChatGPT 中,set_social_webhook_destination 接受 account_id 和 url(填 null 即停止),并返回仅显示一次的签名密钥;再次调用会生成新的密钥。发布事件不会被转发:请改用 get_tiktok_publish_status 跟踪帖子。
set_social_webhook_destination { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/tiktok/" }
=> {
"url": "https://hooks.example.com/tiktok/",
"signing_secret": "whsec_<SECRET>",
"note": "Shown once: store it as a secret. ..."
}如何通过 Partner API 进行设置?
向 https://easycoexistence.com/api/v1 发送 PUT /channels/{id}/webhook 请求,以 ec_live_ 密钥作为 Bearer 令牌,请求体为 {"url": "https://..."}。响应包含 webhook_url、signing_secret 和 note,发送 {"url": null} 即停止转发。URL 必须是公网主机上的 HTTPS;渠道不存在时返回 404 not_found,已移除时返回 409 removed,已暂停时返回 402 suspended。
curl -X PUT "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/webhook" \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/tiktok/"}'
{ "webhook_url": "https://hooks.example.com/tiktok/", "signing_secret": "whsec_<SECRET>", "note": "..." }两种投递有何不同?
由 easyCoexistence 转发的投递,其签名方式和结构与 TikTok 自身的投递不同,因此为其中一种编写的接收端需要为另一种做出调整。转发的负载保留 TikTok 的评论字段,其中 content 已被解析,ID 为字符串;变化的是每次投递的签名、权限范围和重试方式:
| TikTok to your app | easyCoexistence to your endpoint | |
|---|---|---|
| Header | Tiktok-Signature: t=<unix>,s=<hex> | X-EC-Signature: t=<unix>,v1=<hex> |
| Key | The developer app's secret | The account's signing secret, shown once |
| Events | VIDEO and COMMENT, per app | comment.update, per connected account |
| Body | client_key, event, create_time, user_openid, content as a string | platform, account_id, external_id, entry with content parsed |
| Retries | Up to 72 hours | None: one attempt, 8 seconds, no redirects |
设置方法
- Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
- Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
- Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
- Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
- Handle repeatsKey each event on its content, such as comment_id with comment_action, or publish_id with the event name, before acting on it.
常见错误
- 在应答之前就处理事件。TikTok 要求立即返回 200,并会重试它未见确认的投递,因此应先将任务放入队列,再进行应答。
- 不小心在第一次 COMMENT 订阅时发送了 item_list。此后,TikTok 只会报告列出帖子的评论事件。
- 使用访问令牌进行验证。TikTok 使用应用密钥为 Webhook 签名,即 /business/webhook/update/ 所接受的那个密钥。
- 将两个环境指向同一个应用。每个应用的每种事件类型只保留一个 callback_url,新的 /business/webhook/update/ 调用会替换它。
可通过 Claude 或 ChatGPT 中的 set_social_webhook_destination,或使用 PUT /channels/{id}/webhook 进行设置。每个连接每月从 US$ 9 降至 US$ 0.75,连接越多越便宜,前 3 天免费试用。
常见问题
TikTok 的 Webhook 投递携带哪些请求头?
tiktok-signature、webhook-schema-version(当前为 v1.0)和 x-tt-logid(投递 ID)。JSON 请求体包含 client_key、event、create_time、user_openid 和 content。
发布视频后,TikTok 会发送 Webhook 吗?
会,事件类型为 VIDEO:TikTok 下载并检查文件后发送 post.publish.complete,帖子公开后再发送 post.publish.publicly_available,其中包含 post_id。
TikTok 对失败的 Webhook 投递会重试多久?
最长 72 小时,以指数退避方式重试,之后丢弃该事件。投递至少一次,因此请预期会出现重复。
我能否在 easyCoexistence 的 TikTok 应用上注册自己的回调 URL?
不能。应用的 Webhook 设置由 easyCoexistence 保留。set_social_webhook_destination 则会将账户的评论事件发送给您。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间