webhook.url,当任务进入 COMPLETED 或 FAILED 时,querying.ai 会把结果 POST 到该地址。
投递负载
每次投递都是一个Content-Type: application/json 的 POST,正文如下:
例如,一个已完成的 Perplexity 任务(Perplexity 为 1 积分):
验证签名
用 API 密钥提交的任务会用该密钥签名。每次投递都携带三个请求头:
HMAC 密钥是提交该任务的 API 密钥(批次则为创建批次的密钥)的 32 字节 SHA-256 摘要。请在解析之前对原始正文计算签名,使用恒定时间比较,并只接受五分钟以内的时间戳:
重试
在 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,并在所有项目结束后再发送一个完成事件:
querying-webhook-id 为 batch_<batch id>,并遵循相同的重试计划。该事件只在 createdAt 起 30 天内、批次可读取期间发送。
下一步
异步任务
状态、轮询和保留期。
批次与网格
数千个任务共用一个 webhook URL。