Skip to main content

概述

与其反复轮询 GET /jobs/{id},你可以提供一个 webhook URL,让任务完成时收到 POST 请求。这更高效,并减少不必要的 API 调用。

使用 Webhooks

在任意生成请求中添加 X-Webhook-URL 请求头。当任务进入终态(completed、failed 或 cancelled)时,API 会向你的 URL 发送一次带有完整任务数据的 POST 请求。

Webhook 载荷

任务完成时,你的 webhook URL 会收到带任务数据的 POST 请求:

最佳实践

快速响应 - 尽快返回 2xx 状态码。如果需要,可以异步处理 webhook 数据。
验证载荷 - 在处理结果之前,先确认 job_id 对应的是你发起的任务。
  • 出于安全考虑使用 HTTPS 端点
  • 实现幂等,以防重复投递
  • 记录 webhook 收到的日志以便调试

Webhooks 与轮询

如果你有可以接收 HTTP 请求的服务器,建议使用 webhooks。对于客户端应用或无法公开端点的场景,则使用轮询。

下一步

任务生命周期

了解任务状态和状态轮询

代码示例

查看包含 webhook 处理的完整示例