登录开始免费试用
easyCoexistence 官方 API

设置 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 端点,使用其自有的签名密钥。

72 hours

TikTok 在丢弃未收到 HTTP 200 响应的投递前,以指数退避方式重试的时长

100

单个 item_list 可指定的帖子 ID 数量上限,用于将 comment.update 事件限定在特定帖子上

v1.0

TikTok 随每次投递发送的 webhook-schema-version 请求头的当前值

No permission

TikTok 参考文档中列出的 Webhook 配置端点,这些端点使用 app ID 与应用密钥进行身份验证

HMAC-SHA256

Tiktok-Signature 背后的算法:时间戳、点号和请求体拼接而成,以应用密钥为键,并以十六进制编码

Business Comment

订阅 comment.update 所需的应用权限位于 TikTok Accounts 之下,发布事件则需要 Business Content 权限

TikTok 账户应用可以接收哪些 Webhook 事件?

有两类事件,各自作为独立的 event_type 订阅。VIDEO 涵盖通过 /business/video/publish/ 或 /business/photo/publish/ 发布的帖子,COMMENT 涵盖账户的图文帖子和公开视频帖子上的评论,无论这些帖子是通过 API 还是 TikTok 应用发布的:

post.publish.failedVIDEO: the post broke a format rule or its URL was blocked before the download finished
post.publish.completeVIDEO: the file met the format rules and downloaded without problems
post.publish.publicly_availableVIDEO: moderation passed and the post is public, with its post_id
post.publish.no_longer_publicly_availableVIDEO: later moderation, or the owner, took the post out of public view
comment.updateCOMMENT: a comment or reply created, deleted, hidden, set to friends only or made public

订阅之前,应用需要什么?

需要 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。

Subscribe the app to comment events
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 时产生差异。

Verify a TikTok webhook in Python
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 a destination through MCP
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。

Set a destination with the Partner API
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 appeasyCoexistence to your endpoint
HeaderTiktok-Signature: t=<unix>,s=<hex>X-EC-Signature: t=<unix>,v1=<hex>
KeyThe developer app's secretThe account's signing secret, shown once
EventsVIDEO and COMMENT, per appcomment.update, per connected account
Bodyclient_key, event, create_time, user_openid, content as a stringplatform, account_id, external_id, entry with content parsed
RetriesUp to 72 hoursNone: one attempt, 8 seconds, no redirects

设置方法

  1. Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
  2. Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
  3. Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
  4. Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
  5. 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/ 调用会替换它。
使用 EasyCoexistence 完成这些操作

可通过 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 监控

验证时间