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 代理地址：

在浏览器中，访问 https://smee.io/
点击 “Start a new channel”
复制“Webhook Proxy URL”下的完整地址。您将在后续设置步骤中使用此地址。

转发 webhooks：

如果您尚未安装 smee-client，请在终端中运行以下命令。

npm install --global smee-client

要接收来自 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

在测试 webhook 期间，请保持此进程持续运行。当您想停止转发 webhook 时，输入 Ctrl+C 即可。
请注意，路径为 /webhook，端口为 3000。日后当您希望搭建自己的代码来接收 webhook 投递时，这些值可能会派上用场。

创建 webhook：

现在，您可以使用该 Webhook 代理地址，在 Webhooks 页面上创建一个新的 webhook。

示例响应

当任务状态发生变化时，Meshy 会向您配置的 URL 发送一个 webhook payload。该 payload 以 JSON 格式包含任务对象。有关所有任务对象属性的完整说明及示例 payload，请参阅：