Throk Webhook 設定教學：建立規則、推送格式與驗證簽章

Webhook 讓你不用一直輪詢 API：只要設定好規則，Threads 上出現符合條件的串文時，Throk 會主動把串文資料 POST 到你指定的網址。常見用途：

品牌或產品被提及、而且開始有熱度時，推送到 Slack、LINE 或內部系統
監測話題中讚數、回覆數或瀏覽數超過門檻的串文
把「正在爆紅」的串文自動匯入你的資料庫或 CRM

運作方式

Webhook 由兩個部分組成：

端點（Endpoint）：接收通知的網址，例如 https://example.com/throk-webhook。每個端點有自己的簽章密鑰。
規則（Rule）：決定什麼樣的串文要推送。每條規則掛在一個端點上，一個端點可以有多條規則。

Throk 每 3 分鐘檢查一次所有規則。符合條件的串文，會以一篇串文一則事件的方式送到端點。同一篇串文對同一條規則只會送出一次。

規則類型

關鍵字規則

串文內容包含指定關鍵字，而且達到你設定的門檻時推送。

每條規則一個關鍵字，比對方式與關鍵字搜尋相同：中文逐字比對、英文以單字比對。
檢查範圍是最近 24 小時內發佈的串文。
門檻至少要設定一項，最低值如下：讚數 ≥ 10、回覆數 ≥ 5、瀏覽數 ≥ 1,000。

兩種規則的共同點

同一條規則裡的門檻是「且」：例如讚數 ≥ 100 且回覆數 ≥ 10。
不同規則之間互不影響：一篇串文符合兩條規則，就會送出兩則事件。
可以依串文語言篩選：zh（所有中文，預設）、zh-Hant（繁體中文）、zh-Hans（簡體中文）、yue（粵語）、ja（日文）、ko（韓文）。語言依每篇串文本身的語言判斷，不看作者所在地；zh 包含 zh-Hant、zh-Hans 與 yue。
包含回覆：回覆也可能觸發規則，事件中的 is_reply 欄位可以區分。
瀏覽數門檻會比較晚觸發：串文的瀏覽數通常要發文後數小時才有資料，設定瀏覽數門檻的規則會比只看讚數、回覆數的規則晚送出。

推送上限

每條規則都可以設定推送上限，不設定就是不限：

hourlyLimit：每小時上限，以 UTC 整點計算。
dailyLimit：任意連續 24 小時的上限，不是按日曆日計算。

達到上限時會先推送互動最高的串文：規則有讚數門檻就比讚數，沒有就比回覆數，只設瀏覽數門檻時比瀏覽數，數字相同時先推送較新的串文。其餘串文不會排隊：每次檢查都會用當下的數字重新排序，之後有額度、又輪到它才會推送，超過檢查範圍就不再推送，也不會計費。

兩張示意圖。第一張追蹤一條關鍵字規則一天符合的 61 篇串文，每小時上限 2 則，讚數高的排在上面：30 篇在 1 小時內推送，幾乎都是讚數最高的串文；18 篇延後推送，讚數居中；13 篇漏掉，都是讚數最低的串文，等滿 24 小時都沒輪到。第二張：每天符合 1,000 篇時，只設每日 120 則會在第 1 次檢查用完，其餘 23 小時都是 0 則，最熱門的串文也要等到第 24 小時；再加上每小時 5 則，每小時推送讚數最高的 5 篇，熱門串文很快就收到

剛發佈的串文可能較晚送出：新串文的互動通常還不高，會排在較早發佈、互動已累積的串文後面。
估算每天漏掉多少：每天最多推送的數量是「每小時上限 × 24」和 dailyLimit 中較小的一個，一天符合的串文數超過它時，差額大約就是每天漏掉的數量。以圖中的規則為例，61 篇減去 2 × 24，每天約漏掉 13 篇。
不要只設 dailyLimit：額度可能在一次檢查內用完，之後最多要等 24 小時才會再推送，再熱門的串文也一樣，建議同時設定 hourlyLimit。

在開發者平台設定

登入開發者平台，進入 端點與規則。
按 新增端點，輸入你的網址後按建立。
在端點下方按 + 新增規則，選擇 關鍵字 或 熱門門檻，設定語言與門檻（熱門門檻另外設定「過去幾小時」），按新增。
按端點上的測試，確認你的伺服器可以收到事件。建立端點後隨時可以測試，不需要先新增規則；測試事件不扣積分。
展開端點可以看到 簽章密鑰，用來驗證簽章。

開發者平台的 Webhook 通知頁面：在端點下新增關鍵字規則，設定語言與讚數、回覆數、瀏覽數門檻

所有送出的事件、接收端的回應狀態，都可以在 發送紀錄 頁面查看；失敗的事件可以重新發送。

用 API 設定

也可以用 API 管理端點與規則，請求都需要帶上 API 金鑰。

方法與路徑	用途
`GET /webhook/endpoints`	列出你的端點、簽章密鑰（`secret`）與規則
`POST /webhook/endpoints`	建立端點
`DELETE /webhook/endpoints/{endpoint_id}`	刪除端點（連同它的所有規則）
`POST /webhook/endpoints/{endpoint_id}/rules`	在端點下建立規則
`DELETE /webhook/rules/{rule_id}`	刪除規則
`POST /webhook/endpoints/{endpoint_id}/test`	送出一則測試事件（免費）

建立端點：

curl -X POST 'https://premium-api.throk.ai/webhook/endpoints' \
  -H 'Authorization: Bearer sk-throk-...' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/throk-webhook"}'

建立關鍵字規則（讚數 ≥ 100 的繁體中文串文）：

curl -X POST 'https://premium-api.throk.ai/webhook/endpoints/{endpoint_id}/rules' \
  -H 'Authorization: Bearer sk-throk-...' \
  -H 'Content-Type: application/json' \
  -d '{"keyword": "珍珠奶茶", "likeCount": 100, "language": "zh-Hant"}'

建立熱門門檻規則（過去 6 小時內、讚數 ≥ 1,000 的串文）：

curl -X POST 'https://premium-api.throk.ai/webhook/endpoints/{endpoint_id}/rules' \
  -H 'Authorization: Bearer sk-throk-...' \
  -H 'Content-Type: application/json' \
  -d '{"likeCount": 1000, "lookbackHours": 6}'

規則的欄位：

欄位	說明
`keyword`	關鍵字。不填就是熱門門檻規則
`likeCount`、`replyCount`、`viewCount`	讚數、回覆數、瀏覽數門檻，至少填一項
`hourlyLimit`、`dailyLimit`	這條規則每小時（UTC 整點）、任意連續 24 小時最多推送幾則事件，最少 1。不設定代表不限
`lookbackHours`	檢查過去幾小時內發佈的串文，1–72。熱門門檻規則必填；關鍵字規則固定檢查最近 24 小時，不能設定（會回傳 400）
`language`	串文語言：`zh`、`zh-Hant`、`zh-Hans`、`yue`、`ja`、`ko`（不分大小寫），預設 `zh`。回應一律使用上列寫法

欄位名稱也可以用底線寫法，例如 like_count、lookback_hours；回應一律使用上表的寫法。

規則無法修改，要調整時請刪除後重新建立（開發者平台上可以直接編輯）。

推送格式

每則事件以 POST 送到你的端點，內容是 JSON：

{
  "post": {
    "url": "https://threads.com/post/DXZoK1VlEvT",
    "code": "DXZoK1VlEvT",
    "caption": "串文內容……",
    "is_reply": false,
    "like_count": 1700,
    "reply_count": 293,
    "repost_count": 40,
    "reshare_count": 180,
    "impression_count": 254300,
    "post_timestamp": 1776760127,
    "media_url": ["https://media01.throk.ai/media/..."]
  },
  "user": {
    "username": "throk.ai",
    "full_name": "Throk｜定義 Threads 數據新標準",
    "profile_picture": "https://media01.throk.ai/profile/77928681697.jpg"
  },
  "rule": {
    "id": "9b2f6c1e-…",
    "type": "keyword",
    "keyword": "珍珠奶茶"
  }
}

數字是送出當下的快照，之後串文繼續成長也不會再送更新。
repost_count 包含轉發與引用；impression_count 在還沒有瀏覽數資料時為 null。
rule 是觸發這則事件的規則：id 是規則 ID（與建立規則時回傳的相同），type 是 keyword（關鍵字規則）或 trending（熱門門檻規則），keyword 在熱門門檻規則為 null。一篇串文符合多條規則時，每條規則各送一則事件。
測試事件的 rule 是 {"id": "test", "type": "test", "keyword": null}，可以用來和正式事件區分。

驗證簽章

每則事件都附有簽章，讓你確認請求真的來自 Throk、內容沒有被竄改。

簽章密鑰在開發者平台展開端點即可看到，也可以從 GET /webhook/endpoints 回應的 secret 欄位取得。
簽章放在請求標頭 X-Throk-Signature，格式為 t=<UNIX 時間戳>,v1=<簽章>。
驗證方式：以簽章密鑰為金鑰，對 <時間戳>,<原始請求內容> 計算 HMAC-SHA256（十六進位），與 v1 比對；並檢查時間戳是否在幾分鐘內，避免重放攻擊。

Node.js 範例：

import crypto from 'node:crypto';

// rawBody: 原始請求內容（字串），header: X-Throk-Signature 的值
function verify(rawBody, header, secret) {
  const fields = header.split(',').map((p) => p.split('='));
  const t = Number(fields.find(([k]) => k === 't')?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 只接受 5 分鐘內的請求
  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${t},${rawBody}`).digest('hex'),
  );
  // 更換密鑰期間可能同時帶有多個 v1，符合任一個即可
  return fields
    .filter(([k]) => k === 'v1')
    .some(([, sig]) => {
      const got = Buffer.from(sig);
      return got.length === expected.length && crypto.timingSafeEqual(got, expected);
    });
}

請用原始的請求內容（raw body）計算，不要先解析成 JSON 再轉回字串。

接收端要注意的事

請盡快回應 HTTP 2xx；耗時的處理請放到背景執行。
沒有回應 2xx 的事件會以指數退避方式自動重試，最多 10 次；也可以在開發者平台的 發送紀錄 手動重新發送。
每個端點每 60 秒最多接收 1,000 則事件，超過的會延後送出。
正式事件都帶有 X-Convoy-Idempotency-Key 標頭（測試事件沒有），同一則事件重試時值不變，可以用它（或串文的 code）做去重複，避免重複處理。

計費

每送出一則事件扣 20 積分，與 API 呼叫共用帳戶積分。同一篇串文對同一條規則只會扣一次。扣點以事件送出為準，不論你的伺服器是否回應成功，請確保端點可以正常接收。
建立、刪除端點與規則，以及測試事件都不扣積分。
積分不足時事件會暫停送出；補足積分後，仍在檢查範圍內的串文會在下一輪送出。
方案降級到不含 Webhook 的方案後，既有規則會保留，但不會再觸發。
Webhook 的消耗會出現在 積分消耗紀錄，API 類型為 webhook。

停用

Webhook 沒有暫停開關。要停止推送，請刪除規則或端點：刪除端點會一併刪除它的所有規則。

Webhook 的功能介紹與適用方案，請見 Throk Webhook。