Webhooks

讓 Meshy 在 API 任務取得進展或完成時向你的伺服器發送 POST 請求，這樣你就無需輪詢了。

為什麼要使用 webhook

與為每個任務的狀態輪詢 API 相比，webhook 所需的工作更少、成本也更低。Meshy 會在更新發生時立即發送，因此你能更快收到更新，而且 webhook 比輪詢更具可擴充套性。同時你發送的請求也更少，可以讓你離速率限制更遠一些。

設定 webhook

要新增 webhook，請按以下步驟操作：

在開發者平台中開啟 Webhooks 頁面，然後點擊 Create Webhook。
在 Payload URL 中，輸入接收投遞的地址。Meshy 只透過 https:// 進行投遞。
儲存對話框中自動填入的 Webhook Secret 副本。每次投遞都會攜帶它，便於你的伺服器驗證請求確實來自 Meshy。對於你已有的 webhook，可以點擊其 Secret 欄中的眼睛圖示來查看它。
勾選 Active，然後點擊 Confirm。

每個帳戶最多可以有 5 個處於啟用狀態的 webhook，總數上限為 10 個。每個啟用狀態的 webhook 都會收到你所有 API 任務的狀態更新。

如果要用本機上的伺服器測試 webhook，請參閱在本機進行測試。

處理投遞

要接受一次投遞，請回傳低於 400 的狀態碼進行回應，例如 200 或 202。Meshy 大約會等待 25 秒以取得回應，因此請先儲存投遞內容再進行回應，然後再去做比較耗時的工作，例如下載模型。

狀態碼為 400 及以上，或沒有回應，都會被視為投遞失敗。Meshy 會以逐漸延長的間隔進行重試，對於 IN_PROGRESS 更新最多重試 4 次，對於最終狀態最多重試 9 次。如果連續 20 次更新的每次重試都失敗，Meshy 可能會停用該 webhook。要重新啟用它，請在 Webhooks 頁面編輯它並勾選 Active。

請針對以下情況編寫你的程式碼：

投遞可能會亂序到達。一次 IN_PROGRESS 投遞可能會在最終投遞之後到達，因此不要讓它覆蓋最終狀態。
同一次更新可能會被投遞多次。請確保每一對 id 和 status 只被處理一次。
任何知道你地址的人都可以向其發送請求。請將 X-MESHY-API-WEBHOOK-SECRET-KEY 與你儲存的密鑰副本進行比較，拒絕不相符的請求。

如果某個任務的最終投遞在超過其典型耗時大約兩倍的時間後仍未到達，請透過該任務的 GET endpoint 取得任務資訊。關於典型耗時以及應等待多久，請參閱任務生命週期。

在本機進行測試

Meshy 只向公開的 https:// 地址進行投遞，因此無法直接連接到你本機上的伺服器。要在本機測試程式碼，可以使用 webhook 代理將公開地址轉發到本機。以下步驟使用 smee.io，不過任何 webhook 代理服務的使用方式都是類似的。

開啟 smee.io 並點擊 Start a new channel。複製 Webhook Proxy URL 下方的地址。
如果你還沒有安裝 smee 用戶端，請先安裝它：
```
npm install --global smee-client
```
將該通道轉發到你的伺服器。請將 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
```
在測試期間請保持其運行。要停止轉發，請按 Ctrl+C。你的伺服器會在埠 3000 的 /webhook 路徑上接收投遞，因此請將你的程式碼設定為監聽該路徑。
在 Webhooks 頁面上，建立一個 webhook，並將 Webhook 代理地址作為其 Payload URL。

投遞 payload

Meshy 會在任務處於 IN_PROGRESS 狀態時發送一次投遞，並在任務達到最終狀態時再發送一次。一個任務也可能在沒有 IN_PROGRESS 投遞的情況下直接達到最終狀態。

每次投遞都是向你的回撥地址發送的一次 POST 請求，包含以下請求標頭：

Header	值
`X-MESHY-API-WEBHOOK-SECRET-KEY`	該 webhook 的密鑰
`X-MESHY-API-WEBHOOK-USER-ID`	擁有該 webhook 的 Meshy 使用者的 ID
`Meshy-Webhook-Version`	`v1`，表示請求體的格式
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

JSON 請求體就是任務物件。它與該任務的 GET endpoint 回傳的物件相同，只是 progress 欄位不同。一次投遞中 progress 會是以下值之一：

任務處於 IN_PROGRESS 狀態時為 50
任務成功時為 100
任務失敗或被取消時為 0

關於每種任務物件的欄位及範例，請參閱以下各節：