Webhooks

Webhooks 讓您能在 Meshy 的 API 任務完成或狀態發生變化時接收即時更新。設定完成後，Meshy 會以 json 格式將事件 payload 以 POST 方式傳送到您指定的 URL。

為什麼要建立 Webhooks

使用 webhooks 有諸多優勢，尤其是在自動檢查 API 任務狀態方面。相比持續輪詢 API 來取得任務狀態更新，webhooks 所需的工作量和成本更低。Webhooks 還能實現近乎即時的更新，並且相較於 API 輪詢具有更好的可擴充性。這也能幫助您更妥善地管理速率限制，尤其是在您持續進行輪詢的情況下。

設定與配置

要啟用 webhooks，請在開發者平台中開啟 Webhooks 頁面，然後點擊「建立 Webhook」按鈕。提供您希望接收 webhooks 的目標 https URL，並啟用該 webhook 以自動接收來自 Meshy 的任務更新。每個 Meshy 帳戶最多可擁有 5 個處於啟用狀態的 webhooks。當某個 webhook 被啟用後，所有 API 任務狀態更新都會自動傳送到該回呼地址。出於安全考量，目前我們僅允許將 webhooks 傳送到 https URL。如果您想設定本機測試，請參閱以下章節。

Webhook 投遞要求

為使您的 webhook 正常運作並持續接收事件：

您的伺服器必須回傳低於 400 的 HTTP 狀態碼（例如 200 OK、202 Accepted）。
任何狀態碼 >= 400 的回應都將被視為投遞失敗。
連續多次失敗可能會：
- 導致 progress 更新延遲或錯序到達
- 在多次嘗試失敗後自動停用您的 webhook（詳見自動停用策略）

提示： 在驗證並儲存 webhook payload 後，請務必回傳成功回應，即使後續處理是非同步進行的。

如果某個任務的最終事件在大約為其典型耗時兩倍的時間後仍未到達，請使用該任務的 GET 端點來取得任務資訊。有關典型耗時及應等待多久，請參閱任務生命週期。

轉發 Webhooks 以進行本機測試

如果您想在本機測試您的 webhook 程式碼（本機地址通常為 http 地址），可以使用 Webhook 代理地址將 webhooks 轉發到您的電腦或 codespace。以下是使用 smee.io 的建議步驟，但您也可以使用任何您喜歡的服務來產生 Webhook 代理地址。

取得 Webhook 代理地址：

在瀏覽器中，造訪 https://smee.io/
點擊「Start a new channel」
複製「Webhook Proxy URL」下方的完整 URL。您將在後續設定步驟中使用此 URL。

轉發 webhooks：

如果您尚未安裝 smee-client，請在終端機中執行以下指令。

npm install --global smee-client

要接收來自 smee.io 轉發的 webhooks，請在終端機中執行以下指令。將 WEBHOOK_PROXY_URL 替換為您先前取得的 Webhook 代理地址。

smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

您應該會看到類似如下的輸出，其中 WEBHOOK_PROXY_URL 是您的 Webhook 代理地址：

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL

在測試 webhook 期間，請保持此程序持續執行。當您想要停止轉發 webhooks 時，按 Ctrl+C 即可。
請注意，此處路徑為 /webhook，連接埠為 3000。當您之後想要建置自己的程式碼來接收 webhook 投遞時，這些值可能會派上用場。

建立 webhook：

現在，您可以使用該 Webhook 代理地址在 Webhooks 頁面上建立一個新的 webhook。

範例回應

當任務狀態發生變化時，Meshy 會以 POST 方式將 webhook payload 傳送到您配置的 URL。該 payload 包含 JSON 格式的任務物件。有關所有任務物件屬性的完整說明及範例 payload，請參閱：