Webhooks

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

為什麼要建立 Webhooks

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

設定與配置

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

Webhook 送達要求

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

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

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

轉發 Webhooks 以進行本機測試

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

取得 Webhook 代理地址：

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

轉發 webhooks：

  1. 如果您尚未安裝 smee-client，請在終端機中執行以下命令。
npm install --global smee-client
  1. 要接收來自 smee.io 轉發的 webhook，請在終端機中執行以下命令。將 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 期間，請保持此程序持續執行。當您想停止轉發 webhook 時，輸入 Ctrl+C 即可。
    請注意，路徑為 /webhook，連接埠為 3000。日後當您希望建置自己的程式碼來接收 webhook 投遞時，這些值可能會派上用場。

建立 webhook：

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

範例回應

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