浏览文档
API 参考
接收、去重并验证异步、批量与 Bulk 任务的完成通知。
本页内容
配置 callback_url
提交异步查询、批量条目或 Bulk 任务时,可提供 443 端口上的公网 HTTPS callback_url(最长 2,048 个字符,不含凭据与 URL 片段)。省略 callback_url,或传入 null / 空字符串即可关闭通知。
在异步与批量请求(POST /v1/queries 与 POST /v1/queries/batch)中,请将 callback_url 放在查询对象顶层、params 之外;在 Bulk 任务(POST /v2/bulk-jobs)中,请将 callback_url 放在请求体顶层、options 之外。
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://example.com/webhooks/flashdata"
}{
"source": "youtube_metadata",
"callback_url": "https://example.com/webhooks/flashdata",
"options": {
"include_formats": false
}
}已保存回调 URL 与单次请求 callback_url 的区别
管理 API 还提供面向控制台的已保存回调 URL 端点 /v2/delivery/webhooks(使用 cookieSession + csrfToken),用于保存可复用回调地址并通过 POST /v2/delivery/webhooks/{webhookId}/test 发送测试载荷。代码集成请在每次提交请求时直接传入 callback_url。
事件载荷与请求头
通知仅用于确认任务已进入 completed 或 failed 状态(或 Bulk 清单已发布)。载荷永远不包含查询结果、媒体文件或你的 API Key。请使用 delivery_id(同时位于 X-Delivery-Id 请求头)对推送去重。
| 字段 | 说明 |
|---|---|
delivery_id | 用于幂等去重的稳定投递标识,与 X-Delivery-Id 请求头一致。 |
| id | 单个任务或 Bulk 任务标识,请与提交时保存的回执比对。 |
| source | 请求的数据来源(例如 google_search 或 youtube_download)。 |
| status | 终态:异步与批量任务为 completed 或 failed;Bulk 任务在清单发布后发送 completed。 |
| links | 需鉴权的管理 API 状态与结果链接。拉取结果前请始终先通过管理 API 校验。 |
{
"delivery_id": "dlv_01JEXAMPLE0000000000000000",
"id": "job_01JEXAMPLE0000000000000000",
"source": "google_search",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000/results",
"method": "GET"
}
]
}{
"delivery_id": "dlv_01JEXAMPLE0000000000000001",
"id": "bulk_01JEXAMPLE0000000000000000",
"source": "youtube_metadata",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000",
"method": "GET"
},
{
"rel": "manifest",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000/manifest",
"method": "GET"
}
]
}重试策略、验证与接收端安全
通知投递(含首次尝试)按指数退避策略总计最多尝试八次。持久化保存 delivery_id 后请及时返回 2xx 响应。
Webhook 事件不带签名。切勿盲信载荷中的 URL 或请求任意主机:请将 id 与 source 与已保存回执比对,使用 X-API-Key 调用 GET /v2/jobs/{id} 或 GET /v2/bulk-jobs/{bulkId} 校验状态,并保留轮询作为兜底机制。
import http from "node:http";
const seen = new Set(); // Replace with durable database storage in production.
http.createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/webhooks/flashdata") {
res.writeHead(404).end();
return;
}
const chunks = [];
req.on("data", chunk => chunks.push(chunk));
req.on("end", () => {
const event = JSON.parse(Buffer.concat(chunks).toString("utf8"));
const deliveryId = String(req.headers["x-delivery-id"] ?? event.delivery_id ?? "");
if (!deliveryId || seen.has(deliveryId)) {
res.writeHead(200).end("ok");
return;
}
seen.add(deliveryId);
// Queue background verification against https://api.flashdata.dev/v2/jobs/{id}
// or /v2/bulk-jobs/{id} with X-API-Key; ignore unverified URLs in event.links.
res.writeHead(200).end("accepted");
});
}).listen(3000);