Webhooks

当 API 任务有进展或完成时，让 Meshy 向你的服务器发送 POST 请求，这样你就无需轮询。

为什么要使用 webhook

与为每个任务的状态轮询 API 相比，webhook 所需的工作更少、成本更低。Meshy 会在更新发生时立即发送，因此你能更快收到更新，而且 webhook 的可扩展性也优于轮询。同时你发送的请求也更少，可以让你离速率限制更远一些。

设置 webhook

要添加 webhook，请按以下步骤操作：

在开发者平台中打开 Webhooks 页面，然后点击 Create Webhook。
在 Payload URL 中，输入接收投递的 URL。Meshy 仅通过 https:// 进行投递。
选择 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 只被处理一次。

如果某个任务的最终投递在超过其典型耗时的大约两倍时间后仍未到达，请通过该任务的 GET endpoint 获取该任务。关于典型耗时以及应等待多长时间，请参阅任务生命周期。

在本地计算机上测试

Meshy 只会投递到公开的 https:// URL，因此无法直接访问你本地计算机上的服务器。要在本地计算机上测试代码，可以使用 webhook 代理将公开 URL 转发到本地。以下步骤使用 smee.io，任何 webhook 代理服务的使用方式都是类似的。

打开 smee.io 并点击 Start a new channel。复制 Webhook Proxy URL 下方的 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 代理地址作为 Payload URL 的 webhook。

投递 payload

当任务处于 IN_PROGRESS 状态时，Meshy 会发送一次投递；当任务到达最终状态时，还会再发送一次。一个任务也可能在没有 IN_PROGRESS 投递的情况下就到达其最终状态。

每次投递都是向你的回拨地址发送的一个 POST 请求，其 JSON 正文为该任务对象。这与该任务的 GET endpoint 所返回的对象相同，只是其中的 progress 不同。一次投递会将 progress 发送为以下值之一：

当任务处于 IN_PROGRESS 时为 50
当任务成功时为 100
当任务失败或被取消时为 0

关于每种任务对象的字段及示例，请参阅以下各节：