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 的完整说明，请参阅：