接收 Webhook

請求標頭	範例	說明
webhook-id	msg_2KWPBg…	冪等鍵。同一事件的所有重試中維持不變。
webhook-timestamp	1614265330	unix 秒。確認是近期值可防止重放。
webhook-signature	v1,g0hM9SsE…	內文的 HMAC-SHA256，base64 編碼。
content-type	application/json	固定為此值。
您註冊的認證標頭名稱	您註冊的認證標頭的值	若已註冊則一併送出。

POST <your endpoint>
content-type: application/json
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1614265330
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

type	data	何時
note.created	單一項目，包含內文	項目被儲存時。並不表示已可搜尋 — 請看 status。
note.ready	{ count, group_id?, items[] }	已儲存的項目變為可搜尋時。每一輪處理依分組各送一次。
note.failed	{ count, group_id?, items[] }	已儲存的項目最終未能變為可搜尋時。項目仍然還在。
note.deleted	{ count, items[{id}] }	項目被刪除時。只有 id——它們已經不存在。
webhook.ping	{}	您按下測試連線時。

單筆儲存

{
  "type": "note.created",
  "timestamp": "2026-09-05T04:12:07Z",
  "data": {
    "id": 41,
    "title": "…",
    "summary": "…",
    "content": "…",
    "created_at": "2026-09-05T04:11:58Z",
    "origin": "Claude",
    "status": "ready",
    "group_id": null
  }
}

上傳的一個分片

{
  "type": "note.created",
  "timestamp": "2026-09-05T04:12:09Z",
  "data": {
    "id": 42,
    "title": "… (3/77, p.47–53)",
    "summary": "…",
    "content": "…",
    "created_at": "2026-09-05T04:12:08Z",
    "origin": "Upload",
    "status": "pending",
    "group_id": "9f2c1ab84e7d4f0b93c5a61d2e8b7c40"
  }
}

上傳的分片變為可搜尋時

{
  "type": "note.ready",
  "timestamp": "2026-09-05T04:31:12Z",
  "data": {
    "count": 2,
    "group_id": "9f2c1ab84e7d4f0b93c5a61d2e8b7c40",
    "items": [
      { "id": 42, "title": "… (3/77, p.47–53)", "status": "ready" },
      { "id": 43, "title": "… (4/77, p.54–60)", "status": "ready" }
    ]
  }
}

上傳的分片搜尋準備失敗時

{
  "type": "note.failed",
  "timestamp": "2026-09-05T04:36:40Z",
  "data": {
    "count": 2,
    "group_id": "9f2c1ab84e7d4f0b93c5a61d2e8b7c40",
    "items": [
      { "id": 44, "title": "… (5/77, p.61–67)", "status": "failed" },
      { "id": 45, "title": "… (6/77, p.68–74)", "status": "failed" }
    ]
  }
}

同一個檔案可能一部分已就緒、一部分失敗：這時兩筆事件會帶著同一個 group_id，相隔幾秒先後送達。

項目被刪除時

{
  "type": "note.deleted",
  "timestamp": "2026-09-05T05:02:44Z",
  "data": { "count": 2, "items": [{ "id": 42 }, { "id": 43 }] }
}

連線測試

{
  "type": "webhook.ping",
  "timestamp": "2026-09-05T05:10:00Z",
  "data": {}
}

單筆儲存——從 MCP、REST API 或儀表板儲存時。只有一筆 note.created，而且一送達就已經可以搜尋。

檔案上傳——檔案會被拆成分片，每個分片各有一筆 note.created。此時都還不能搜尋；準備好之後 note.ready 再另外送來。

	單筆儲存	上傳（一個檔案）
note.created	一筆，status: "ready"，group_id: null	每個分片一筆，status: "pending"，帶 group_id
note.ready	不會送出	分片變為可搜尋時送出
note.failed	不會送出	某個分片無法變為可搜尋時送出
可搜尋時點	note.created	note.ready
可讀取時點	立即	立即——等待的只是搜尋
分片編號	—	不是欄位。只有標題裡的 (3/77) 和 data.id 的順序

• status——表示項目是否可以搜尋。"ready" 是可以，"pending" 是還在準備中，"failed" 是搜尋準備失敗，搜尋不會找到它。
• group_id——一批項目的名字。它在您上傳檔案時簽發，該檔案的每個分片都帶同一個值。它表示分片屬於哪個檔案，而不是第幾個分片，也是把 note.created 和隨後到來的 note.ready 關聯起來的鍵。
• 如果只需要能搜尋的項目——請以 note.ready 為準，跳過 status 為 "pending" 的 note.created。
• 等待中的分片也能立即讀取——內文已經在負載中。若需再次讀取，請用不計入開啟次數的 GET /api/v1/notes/{id}，整批則用 GET /api/v1/notes/group/{group_id}。
• note.ready 不是每個檔案一次——每次只帶上同時準備好的分片，所以處理分批、或某個分片重試過，就會用同一個 group_id 送出多次。count 是這一次帶的筆數，不是整個檔案的分片數，請累加 items。
• note.failed 不表示項目被刪除——它仍然儲存著、也能讀取，失敗的只是搜尋準備。請不要從您的副本中刪除它；刪除另有自己的事件 note.deleted。在儀表板點選重試可以重新準備，若再次失敗會送來一筆新的 note.failed。

要這樣做	否則
立刻回 2xx，稍後處理	超過 25 秒我們會視為失敗並重送。
用 webhook-id 去除重複	同一項目會被處理兩次。
對重複回 200，切勿 429	429 表示「慢一點」，我們會再送一次。
以 data.id 排序	重試可能超越後面的事件；順序不保證。
註冊最終網址	我們不跟隨轉址——3xx 會當場結束遞送。

1. 組出簽章字串：{webhook-id}.{webhook-timestamp}.{原始內文}
2. 推導金鑰：去掉密鑰的 whsec_ 前綴，再對其餘部分做 base64 解碼
3. 計算 HMAC-SHA256，base64 編碼後與 v1, 之後的值比較
4. 檢查 webhook-timestamp 是否在目前時間的數分鐘以內
5. 以收到的原始位元組驗證——把 JSON 解析後再序列化會破壞簽章
6. 使用任何 Standard Webhooks 函式庫（standardwebhooks.com）可代為完成第 1～5 步

簽章密鑰在帳戶頁面，可在那裡複製或更換。

回應	我們的處理
2xx	完成。
408・429・5xx	分別在 15 分鐘、1 小時、3 小時後重試。
完全沒有回應	以相同間隔重試。
3xx 及其他所有 4xx	就此結束——答案不會改變。

即使持續失敗，我們也不會自動停用遞送。在此期間每天最多寄一封信通知您，帳戶頁面會顯示連續失敗次數與最後一次錯誤。

若您的接收端停機超過約四小時，請用 GET /api/v1/notes/changes 追上。