Webhook

Webhook 是 Sofia 在帖文上線或失敗時發起的 HTTP 呼叫。你可以用它把內容同步到電子錶格、通知訊息工具，或在 Zapier 或 n8n 中觸發一個場景。

新增一個

• 1. 給它一個地址。一個公開的 https 地址，Sofia 會把事件發到那裡。
• 2. 選擇事件。post.published 和 post.failed。
• 3. 註冊它。POST /v1/webhooks：簽名金鑰（whsec_…）只會出現在這次回應中。
• 4. 傳送測試。POST /v1/webhooks/{id}/test 會傳送一個 webhook.test 事件，與其他事件一樣帶有簽名。

完整的請求詳見 API 標籤頁：註冊 Webhook。只有由你的應用程式建立的帖文才會被通知。

構建接收端

務必先傳送一次測試並儲存收到的請求本文：它就是約定，比任何描述都更可靠。Sofia 以 POST 方式傳送每個事件，格式為 JSON { id, type, createdAt, data }，並帶有 Sofia-Event-Id、Sofia-Event-Type 和 Sofia-Signature 請求標頭。

• 驗證簽名。Sofia-Signature 的值為 t=<unix time>,v1=<hex>，其中 v1 是用你的金鑰對 <t>.<raw body> 計算的 HMAC-SHA256。請對原始請求本文計算，並拒絕過舊的時間戳。
• 盡快返回 `2xx`，之後再做處理：緩慢的接收端與宕機的接收端無從區分。
• 保持冪等。同一個事件可能到達兩次：請根據 Sofia-Event-Id 去重。

Webhook 不再觸發時

地址無法存取

Sofia 從自己的伺服器發起呼叫：地址必須是公開的 https。重新導向永遠不會被跟隨，10 秒沒有回應即視為失敗。

地址返回錯誤

任何非 2xx 的回應都會觸發重試，分別在 1 分鐘、5 分鐘、30 分鐘和 2 小時之後，最多重試 5 次。請先查看你自己的日誌，再用 POST /v1/webhooks/{id}/test 重現。

帖文不是由你的應用程式建立的

Webhook 只通知由你的應用程式建立的帖文；在介面中建立的帖文不會觸發它。

延伸閱讀

Webhook 告訴你 Sofia 何時採取了行動。要讓 Sofia 採取行動，請使用 Sofia API、sofia CLI 或 MCP 伺服器（API 和 Agents 標籤頁），或者第三方整合。