Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Referensi API

Webhook penyelesaian

Terima, deduplikasi, dan verifikasi notifikasi penyelesaian untuk tugas async, batch, dan Bulk.

Di halaman ini

Konfigurasi callback_url

Berikan callback_url HTTPS publik di port 443 (hingga 2.048 karakter, tanpa kredensial atau fragmen URL) saat mengirim kueri async, item batch, atau pekerjaan Bulk. Abaikan callback_url, atau kirim null atau string kosong, untuk menonaktifkan notifikasi.

Untuk permintaan async dan batch (POST /v1/queries dan POST /v1/queries/batch), letakkan callback_url di tingkat atas objek kueri, di luar params. Untuk pekerjaan Bulk (POST /v2/bulk-jobs), letakkan callback_url di tingkat atas, di luar options.

Kueri async dengan callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Pekerjaan Bulk dengan callback_url
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

URL callback tersimpan vs callback_url per permintaan

Management API juga menyediakan URL callback tersimpan yang dikelola konsol di /v2/delivery/webhooks (cookieSession + csrfToken) untuk menyimpan tujuan yang dapat dipakai ulang dan mengirim payload uji melalui POST /v2/delivery/webhooks/{webhookId}/test. Integrasi API terprogram sebaiknya mengirimkan callback_url langsung pada setiap pengiriman.

Payload acara dan header

Notifikasi mengonfirmasi bahwa pekerjaan mencapai completed atau failed (atau manifes Bulk telah dipublikasikan). Payload tidak pernah berisi hasil kueri, file media, atau kunci API Anda. Deduplikasi pengiriman menggunakan delivery_id (juga dikirim pada header X-Delivery-Id).

BidangArti
delivery_idPengidentifikasi pengiriman stabil untuk deduplikasi idempoten; cocok dengan header X-Delivery-Id.
idID pekerjaan atau pekerjaan Bulk. Cocokkan dengan tanda terima yang disimpan saat pengiriman.
sourceSumber data yang diminta (misalnya google_search atau youtube_download).
statusStatus akhir: completed atau failed untuk async/batch; completed untuk Bulk setelah manifes dipublikasikan.
linksTautan status dan hasil Management API yang terautentikasi. Selalu verifikasi melalui API sebelum mengambil hasil.
Acara penyelesaian async / batch
{
  "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"
    }
  ]
}
Acara penyelesaian 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"
    }
  ]
}

Percobaan ulang, verifikasi, dan keamanan penerima

Pengiriman dicoba hingga total delapan kali, termasuk percobaan pertama, dengan backoff eksponensial. Kembalikan respons 2xx segera setelah menyimpan delivery_id.

Acara webhook tidak bertanda tangan. Jangan pernah mempercayai URL payload begitu saja atau mengambil host sembarangan: cocokkan id dan source dengan tanda terima tersimpan, verifikasi status melalui GET /v2/jobs/{id} atau GET /v2/bulk-jobs/{bulkId} dengan X-API-Key, dan pertahankan polling status sebagai cadangan.

Penerima webhook Node.js minimal
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);