設定 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 將你帳戶的每個留言事件傳送至你的端點,並以其自有的密鑰簽名。
TikTok 對未收到 HTTP 200 回應的傳送,會以指數退避方式重試多久,之後才捨棄。
一個 item_list 最多可指定的貼文 ID 數目,用以將 comment.update 事件限定於特定貼文。
TikTok 每次傳送時附上的 webhook-schema-version 標頭目前值。
TikTok 參考文件為 Webhook 設定端點所列出的內容,這些端點以應用程式 ID 及 secret 進行驗證。
Tiktok-Signature 的演算法:以時間戳、一個句點(.)及請求主體組成訊息,以應用程式 secret 為金鑰計算,並以十六進制編碼。
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。
如何訂閱?
以 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。
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。
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 進行設定?
使用 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。
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 以應用程式 secret 為 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_id 的 post.publish.publicly_available。
TikTok 重試失敗的 Webhook 多久?
最多 72 小時,採指數退避,之後捨棄該事件。傳送屬至少一次,因此應預期會有重複。
我能否在 easyCoexistence 的 TikTok 應用程式上註冊自己的回呼?
不能。應用程式的 Webhook 設定由 easyCoexistence 保留。set_social_webhook_destination 則會改為將帳戶的留言事件發送給你。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期