Chuyển đến nội dung
VI
Lấy khóa API
Duyệt tài liệu

Tham chiếu API

Webhook hoàn tất

Nhận, khử trùng lặp và xác minh thông báo hoàn tất cho tác vụ bất đồng bộ, theo lô và Bulk.

Trên trang này

Cấu hình callback_url

Cung cấp callback_url HTTPS công khai trên cổng 443 (tối đa 2.048 ký tự, không có thông tin xác thực hoặc đoạn URL) khi gửi truy vấn bất đồng bộ, mục theo lô hoặc tác vụ Bulk. Bỏ qua callback_url, hoặc truyền null hay chuỗi rỗng để tắt thông báo.

Đối với yêu cầu bất đồng bộ và theo lô (POST /v1/queries và POST /v1/queries/batch), đặt callback_url ở cấp cao nhất của đối tượng truy vấn, bên ngoài params. Đối với tác vụ Bulk (POST /v2/bulk-jobs), đặt callback_url ở cấp cao nhất, bên ngoài options.

Truy vấn bất đồng bộ với callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Tác vụ Bulk với callback_url
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

URL callback đã lưu so với callback_url theo từng yêu cầu

Management API cũng cung cấp các URL callback đã lưu quản lý qua bảng điều khiển tại /v2/delivery/webhooks (cookieSession + csrfToken) để lưu đích tái sử dụng và gửi payload thử nghiệm qua POST /v2/delivery/webhooks/{webhookId}/test. Các tích hợp API lập trình nên truyền trực tiếp callback_url trong từng yêu cầu gửi.

Payload sự kiện và tiêu đề

Thông báo xác nhận tác vụ đã đạt trạng thái completed hoặc failed (hoặc bản kê Bulk đã được xuất bản). Payload không bao giờ chứa kết quả truy vấn, tệp phương tiện hay khóa API của bạn. Hãy khử trùng lặp bằng delivery_id (cũng được gửi trong tiêu đề X-Delivery-Id).

TrườngÝ nghĩa
delivery_idĐịnh danh gửi ổn định để khử trùng lặp lũy đẳng; khớp với tiêu đề X-Delivery-Id.
idĐịnh danh tác vụ hoặc tác vụ Bulk. Đối chiếu với biên nhận đã lưu khi gửi.
sourceNguồn dữ liệu được yêu cầu (ví dụ: google_search hoặc youtube_download).
statusTrạng thái cuối: completed hoặc failed cho async/batch; completed cho Bulk sau khi xuất bản bản kê.
linksLiên kết trạng thái và kết quả được xác thực của Management API. Luôn xác minh qua API trước khi tải kết quả.
Sự kiện hoàn tất bất đồng bộ / theo lô
{
  "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"
    }
  ]
}
Sự kiện hoàn tất 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"
    }
  ]
}

Thử lại, xác minh và an toàn cho máy chủ nhận

Hệ thống thử gửi tối đa tám lần tổng cộng, bao gồm cả lần thử đầu tiên, với thời gian chờ tăng theo cấp số nhân. Hãy trả về phản hồi 2xx kịp thời sau khi lưu delivery_id.

Sự kiện webhook không có chữ ký. Không bao giờ tin tưởng mù quáng các URL trong payload hay gọi tới máy chủ tùy ý: hãy đối chiếu id và source với biên nhận đã lưu, xác minh trạng thái qua GET /v2/jobs/{id} hoặc GET /v2/bulk-jobs/{bulkId} bằng X-API-Key và duy trì cơ chế kiểm tra định kỳ làm phương án dự phòng.

Máy chủ nhận webhook Node.js tối giản
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);