登入開始免費試用
easyCoexistence 官方 API

設定 TikTok API for Business Webhook

TikTok 的 API for Business 會按每個開發者應用程式及事件類型,將 Webhook 發送至一個回呼 URL。設定時須以 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 設定端點所列出的內容,這些端點以應用程式 ID 及 secret 進行驗證。

HMAC-SHA256

Tiktok-Signature 的演算法:以時間戳、一個句點(.)及請求主體組成訊息,以應用程式 secret 為金鑰計算,並以十六進制編碼。

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。

如何訂閱?

以 POST 呼叫 /business/webhook/update/,每個 event_type 一次。請求主體包括 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 的呼叫:新貼文會加入既有的列表。
  • 沒有 item_list 的 COMMENT 呼叫,且之前未設定:事件來自已授權應用程式的帳戶的貼文。
  • 沒有 item_list 的 COMMENT 呼叫,且列表已存在:已設定的貼文維持不變。

如何查看或移除訂閱?

以 app_id、secret 及 event_type 呼叫 GET /business/webhook/list/,會返回設定。callback_url 只會在該事件類型已有設定時出現,item_list 只會在已設定時出現。以 app_id、secret 及 event_type 呼叫 POST /business/webhook/delete/ 可將其移除。對於 COMMENT,刪除呼叫中若包含 item_list,只會移除該等貼文;若不包含,則所有貼文的留言事件都會停止。

回呼 URL 必須做什麼?

須即時回應。TikTok 以 HTTPS 發送 JSON 的 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 值、一個句點(.)及請求主體組成簽名訊息,以應用程式 secret 為金鑰計算 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 進行設定?

使用 PUT /channels/{id}/webhook,基底 URL 為 https://easycoexistence.com/api/v1,以你的 ec_live_ 金鑰作為 bearer token,請求主體為 {"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 以應用程式 secret 為 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_id 的 post.publish.publicly_available。

TikTok 重試失敗的 Webhook 多久?

最多 72 小時,採指數退避,之後捨棄該事件。傳送屬至少一次,因此應預期會有重複。

我能否在 easyCoexistence 的 TikTok 應用程式上註冊自己的回呼?

不能。應用程式的 Webhook 設定由 easyCoexistence 保留。set_social_webhook_destination 則會改為將帳戶的留言事件發送給你。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期