เรียกดูเอกสาร
เอกสารอ้างอิง API
รับ คัดกรองซ้ำ และตรวจสอบการแจ้งเตือนเมื่อเสร็จสิ้นสำหรับงานแบบ async, batch และ Bulk
ในหน้านี้
ตั้งค่า callback_url
ระบุ callback_url แบบ HTTPS สาธารณะบนพอร์ต 443 (สูงสุด 2,048 อักขระ โดยไม่มีข้อมูลรับรองหรือ URL fragment) เมื่อส่งคิวรีแบบ async รายการ batch หรืองาน Bulk หากต้องการปิดการแจ้งเตือนให้ละเว้น callback_url หรือส่ง null หรือสตริงว่าง
สำหรับคำขอแบบ async และ batch (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 ต่อคำขอ
Management API ยังมีเอนด์พอยต์สำหรับ URL คอลแบ็กที่บันทึกผ่านคอนโซลที่ /v2/delivery/webhooks (cookieSession + csrfToken) เพื่อบันทึกปลายทางที่ใช้ซ้ำได้และส่งเพย์โหลดทดสอบผ่าน POST /v2/delivery/webhooks/{webhookId}/test สำหรับการเชื่อมต่อผ่านโค้ดควรส่ง callback_url โดยตรงในแต่ละคำขอ
เพย์โหลดเหตุการณ์และเฮดเดอร์
การแจ้งเตือนจะยืนยันว่างานถึงสถานะ completed หรือ failed แล้ว (หรือมีการเผยแพร่แมนิเฟสต์ Bulk แล้ว) เพย์โหลดจะไม่มีผลลัพธ์คิวรี ไฟล์สื่อ หรือคีย์ API ของคุณ ให้คัดกรองการส่งซ้ำด้วย delivery_id (ซึ่งส่งมาในเฮดเดอร์ X-Delivery-Id ด้วย)
| ฟิลด์ | ความหมาย |
|---|---|
delivery_id | รหัสการจัดส่งคงที่สำหรับคัดกรองซ้ำแบบ idempotent ตรงกับเฮดเดอร์ X-Delivery-Id |
| id | รหัสงานหรืองาน Bulk ใช้จับคู่กับใบรับที่บันทึกไว้ตอนส่งคำขอ |
| source | แหล่งข้อมูลที่ร้องขอ (เช่น google_search หรือ youtube_download) |
| status | สถานะสุดท้าย: completed หรือ failed สำหรับ async/batch และ completed สำหรับ Bulk หลังเผยแพร่แมนิเฟสต์ |
| links | ลิงก์สถานะและผลลัพธ์ของ Management 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"
}
]
}การลองใหม่ การตรวจสอบ และความปลอดภัยของฝั่งรับ
การจัดส่งจะพยายามรวมสูงสุดแปดครั้ง (รวมครั้งแรก) พร้อมหน่วงเวลาแบบเอ็กซ์โปเนนเชียล ส่งคืนสถานะ 2xx โดยเร็วหลังบันทึก delivery_id
เหตุการณ์เว็บฮุกไม่ได้ลงนาม อย่าเชื่อถือ URL ในเพย์โหลดโดยไม่ตรวจสอบหรือดึงข้อมูลจากโฮสต์ใดก็ได้ ให้จับคู่ id และ source กับใบรับที่บันทึกไว้ ตรวจสอบสถานะผ่าน GET /v2/jobs/{id} หรือ GET /v2/bulk-jobs/{bulkId} ด้วย X-API-Key และคงการโพลสถานะไว้เป็นตัวสำรอง
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);