跳转到主要内容
在任务上设置 webhook.url,当任务进入 COMPLETED 或 FAILED 时,querying.ai 会把结果 POST 到该地址。

投递负载

每次投递都是一个 Content-Type: application/json 的 POST,正文如下: 例如,一个已完成的 Perplexity 任务(Perplexity 为 1 积分):
失败的任务同样会投递:
各任务类型的价格见积分与限制。

验证签名

用 API 密钥提交的任务会用该密钥签名。每次投递都携带三个请求头: HMAC 密钥是提交该任务的 API 密钥(批次则为创建批次的密钥)的 32 字节 SHA-256 摘要。请在解析之前对原始正文计算签名,使用恒定时间比较,并只接受五分钟以内的时间戳:
只有任务没有 API 密钥,或批次的 API 密钥已吊销超过 30 天时,投递才不带签名。如果你创建的所有任务都来自 API 密钥,请拒绝没有有效签名的请求。
轮换密钥后,用新密钥提交的任务会用新密钥签名。之前提交的任务,其投递仍用提交它们的密钥签名。

重试

在 30 秒内返回任意 2xx 即表示确认。其他状态、超时或连接错误都算一次失败尝试。失败的投递会在 2、4、8 和 16 分钟后重试:约 30 分钟内共五次尝试,每次的 querying-webhook-id 相同。第五次失败后放弃投递。 不跟随重定向:3xx 算作失败尝试。 拒绝投递时,请在响应正文中写明原因。正文的前 200 个字符会与状态码一起保存(例如 HTTP 400: sources must not be empty),并显示在控制台和失败通知邮件中。 投递独立于任务运行。webhook 从未送达的任务,在 GET /v1/async/task/{id} 上仍显示 COMPLETED。要找回结果,请在异步任务所述的 24 小时窗口内轮询。

HTML 页面

带 include.html 的任务投递同样的 JSON 正文。页面本身不在正文里:response.html.url 指向页面,你从那里下载。下载不需要 API 密钥;当请求的 Accept-Encoding 允许时,页面以 Brotli 或 gzip 压缩返回,压缩方式写在 Content-Encoding 中。见 HTML 页面。

URL 规则

webhook.url 在提交时校验。违反规则的 URL 会在 webhook.url 字段上以 400 VALIDATION_ERROR 被拒绝。 投递时,主机必须只解析到公网地址,否则该次尝试失败。连接会发往经过校验的地址。

编写安全的处理程序

1

先验证,再快速确认

检查签名,持久化保存负载,然后返回 200。之后再解析并写入数据库,以免处理过慢触发 30 秒超时而导致重试。
2

去重

投递至少一次。跳过已处理过的 querying-webhook-id,或按 task.idempotencyKey 匹配并让写入具备幂等性。
3

按状态分支

显式检查 task.status。失败的任务也会投递 webhook,附带 response.error。

批次完成事件

通过 POST /v1/batches 创建并设置了 webhook.url 的批次,会按上述方式把每个任务的结果发送到该 URL,并在所有项目结束后再发送一个完成事件:
该事件用批次的 API 密钥签名,其 querying-webhook-id 为 batch_<batch id>,并遵循相同的重试计划。该事件只在 createdAt 起 30 天内、批次可读取期间发送。

下一步

异步任务

状态、轮询和保留期。

批次与网格

数千个任务共用一个 webhook URL。