ข้ามไปยังเนื้อหา
TH
รับคีย์ API
เรียกดูเอกสาร

เอกสารอ้างอิง 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

คิวรีแบบ async พร้อม callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
งาน Bulk พร้อม callback_url
{
  "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 เสมอก่อนดึงผลลัพธ์
เหตุการณ์เสร็จสิ้นสำหรับ 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"
    }
  ]
}
เหตุการณ์เสร็จสิ้นสำหรับ 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"
    }
  ]
}

การลองใหม่ การตรวจสอบ และความปลอดภัยของฝั่งรับ

การจัดส่งจะพยายามรวมสูงสุดแปดครั้ง (รวมครั้งแรก) พร้อมหน่วงเวลาแบบเอ็กซ์โปเนนเชียล ส่งคืนสถานะ 2xx โดยเร็วหลังบันทึก delivery_id

เหตุการณ์เว็บฮุกไม่ได้ลงนาม อย่าเชื่อถือ URL ในเพย์โหลดโดยไม่ตรวจสอบหรือดึงข้อมูลจากโฮสต์ใดก็ได้ ให้จับคู่ id และ source กับใบรับที่บันทึกไว้ ตรวจสอบสถานะผ่าน GET /v2/jobs/{id} หรือ GET /v2/bulk-jobs/{bulkId} ด้วย X-API-Key และคงการโพลสถานะไว้เป็นตัวสำรอง

ตัวรับเว็บฮุกแบบย่อด้วย Node.js
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);