跳转到正文
中文
获取 API 密钥
浏览文档

API 参考

完成通知 Webhook

接收、去重并验证异步、批量与 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 之外。

包含 callback_url 的异步查询
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
包含 callback_url 的 Bulk 任务
{
  "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"
    }
  ]
}
Bulk 完成事件
{
  "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} 校验状态,并保留轮询作为兜底机制。

最小化 Node.js Webhook 接收端
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);