Webhooks

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

為什麼建立 Webhooks

使用 webhooks 有幾個優點，尤其是在自動檢查 API 任務狀態方面。相較於持續輪詢 API 以取得任務狀態更新，Webhooks 所需的工作量與成本更低。Webhooks 也可提供近乎即時的更新，最終比 API 輪詢更具可擴充性。這也讓您能更有效地管理速率限制，尤其是在持續輪詢的情況下。

Webhook 傳遞需求

為了讓您的 webhook 正常運作並持續接收事件，您的伺服器必須回應 HTTP 狀態碼小於 400（例如，200 OK，202 Accepted）。 任何狀態碼大於或等於 400 的回應都會被視為傳遞失敗。 多次連續失敗可能會導致進度更新延遲或順序錯亂，並可能導致 webhook 自動停用（請參閱自動停用策略）。

提示： 在驗證並儲存 webhook 酬載後，請一律回傳成功回應，即使後續處理是非同步執行。

設定與組態

若要啟用 webhooks，請在登入 Meshy 網頁應用程式時前往 API 設定頁面。在您的 API 金鑰下方找到「Webhooks」區段，然後按一下「建立 Webhook」按鈕。提供您希望用來接收來自 Meshy 的 webhooks 的 https URL，並啟用 webhook，即可自動接收來自 Meshy 的任務更新。 每個 Meshy 帳戶最多可以有 5 個啟用中的 webhooks。啟用 webhook 時，所有 API 任務狀態更新都會自動傳送到酬載 URL。基於安全考量，我們目前僅允許將 webhooks 傳送到 https URL。如果您想設定本機測試，請參閱以下章節。

本機測試的 Webhook 轉送

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

取得 Webhook 代理地址：

  1. 在您的瀏覽器中，前往 https://smee.io/
  2. 按一下「Start a new channel」
  3. 複製「Webhook Proxy URL」下方的完整 URL。您將在以下設定步驟中使用此 URL。

轉送 webhooks：

  1. 如果您尚未安裝 smee-client，請在終端機中執行以下命令。
npm install --global smee-client
  1. 若要從 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
  1. 測試您的 webhook 時請保持此程式執行。當您想停止轉送 webhooks 時，請按 Ctrl+C。 請注意，路徑是 /webhook，連接埠是 3000。當您稍後想要設定自己的程式碼來接收 webhook 傳遞時，這些值可能會派上用場。

建立 webhook：

您現在可以使用 Webhook 代理地址，在 Meshy API 設定頁面中建立新的 webhook。

範例回應

當任務狀態發生變化時，Meshy 會將 webhook 酬載 POST 到您設定的 URL。該酬載包含 JSON 格式的任務物件。如需任務物件所有屬性的完整說明和範例酬載，請參閱：