Webhooks

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

為什麼要建立 Webhooks

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

設定與配置

要啟用 webhooks，請在登入 Meshy Web 應用程式後，前往 API 設定頁面。在您的 API Keys 下方找到「Webhooks」區塊，然後點擊「Create Webhook」按鈕。提供您希望用來接收 webhooks 的 https URL，並啟用該 webhook，以自動接收來自 Meshy 的任務更新。 每個 Meshy 帳戶最多可以擁有 5 個啟用中的 webhooks。當某個 webhook 被啟用後，所有 API 任務狀態更新都會自動傳送到該回撥地址。出於安全考量，目前我們僅允許向 https URL 傳送 webhooks。如果您想設定本機測試，請參閱下一節。

Webhook 傳遞要求

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

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

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

轉發 Webhooks 以進行本機測試

如果您想在本機測試您的 webhook 程式碼（通常位於 http 地址），可以使用 webhook 代理地址 將 webhooks 轉發到您的電腦或 codespace。以下是使用 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 payload 透過 POST 方式傳送到您設定的 URL。該 payload 以 JSON 格式包含任務物件。有關所有任務物件屬性及範例 payload 的完整說明，請參閱：