Jelajahi dokumentasi
Referensi API
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.
{
"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 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).
| Bidang | Arti |
|---|---|
delivery_id | Pengidentifikasi pengiriman stabil untuk deduplikasi idempoten; cocok dengan header X-Delivery-Id. |
| id | ID pekerjaan atau pekerjaan Bulk. Cocokkan dengan tanda terima yang disimpan saat pengiriman. |
| source | Sumber data yang diminta (misalnya google_search atau youtube_download). |
| status | Status akhir: completed atau failed untuk async/batch; completed untuk Bulk setelah manifes dipublikasikan. |
| links | Tautan status dan hasil Management API yang terautentikasi. Selalu verifikasi melalui API sebelum mengambil hasil. |
{
"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"
}
]
}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.
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);