概述
与其反复轮询GET /jobs/{id},你可以提供一个 webhook URL,让任务完成时收到 POST 请求。这更高效,并减少不必要的 API 调用。
使用 Webhooks
在任意生成请求中添加X-Webhook-URL 请求头。当任务进入终态(completed、failed 或 cancelled)时,API 会向你的 URL 发送一次带有完整任务数据的 POST 请求。
Webhook 载荷
任务完成时,你的 webhook URL 会收到带任务数据的 POST 请求:最佳实践
快速响应 - 尽快返回 2xx 状态码。如果需要,可以异步处理 webhook 数据。
- 出于安全考虑使用 HTTPS 端点
- 实现幂等,以防重复投递
- 记录 webhook 收到的日志以便调试
Webhooks 与轮询
如果你有可以接收 HTTP 请求的服务器,建议使用 webhooks。对于客户端应用或无法公开端点的场景,则使用轮询。
下一步
任务生命周期
了解任务状态和状态轮询
代码示例
查看包含 webhook 处理的完整示例