Webhooks

Webhooks允许您在Meshy的API任务完成或状态更改时接收实时更新。一旦配置完成，Meshy将以json格式将事件payload POST到您指定的URL。

为什么创建Webhooks

使用webhooks有几个优势，特别是在自动检查API任务状态方面。Webhooks比持续轮询API以获取任务状态更新所需的努力和成本更少。Webhooks还允许接近实时的更新，并最终比API轮询更具可扩展性。这也使您能够更好地管理速率限制，特别是在您不断轮询的情况下。

设置与配置

要启用webhooks，请在登录Meshy Web应用程序时导航到API设置页面。在您的API Keys下找到“Webhooks”部分，然后点击“创建Webhook”按钮。提供您希望从中接收webhooks的https URL，并启用webhook以自动接收来自Meshy的任务更新。 每个Meshy账户最多可以有5个活动webhooks。当webhook启用时，所有API任务状态更新将自动发送到回拨地址。出于安全考虑，目前我们仅允许将webhooks发送到https URL。如果您想配置本地测试，请参阅以下部分。

Webhook传递要求

为了使您的webhook正常工作并继续接收事件：

  • 您的服务器必须以低于400的HTTP状态码响应（例如，200 OK，202 Accepted）。
  • 任何状态码为>= 400的响应将被视为传递失败。
  • 多次连续失败可能会：
    • 导致progress更新延迟或顺序错误
    • 在多次尝试后自动禁用您的webhook（请参阅自动禁用策略）

提示： 在验证和存储webhook payload后，即使进一步处理是异步进行的，也要始终返回成功响应。

用于本地测试的Webhooks转发

如果您希望在本地测试您的webhook代码，通常是在一个http地址，您可以使用Webhook代理地址将webhooks转发到您的计算机或代码空间。以下是使用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将POST一个webhook payload到您配置的URL。payload包含JSON格式的任务对象。有关所有任务对象属性的完整描述和示例payload，请参阅：