تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

مرجع API

إشعارات الإكمال (Webhooks)

استقبل إشعارات إكمال المهام غير المتزامنة والدفعات والـ Bulk وأزل التكرار وتحقق منها.

في هذه الصفحة

إعداد callback_url

زوّد عنوان callback_url عامًا عبر HTTPS على المنفذ 443 (حتى 2,048 حرفًا دون بيانات اعتماد أو جزء URL) عند إرسال الاستعلامات غير المتزامنة أو عناصر الدفعة أو مهام Bulk. احذف callback_url أو مرّر null أو سلسلة فارغة لتعطيل الإشعارات.

في الطلبات غير المتزامنة والدفعات (POST /v1/queries وPOST /v1/queries/batch)، ضع callback_url في المستوى الأعلى لكائن الاستعلام خارج params. وفي مهام Bulk (POST /v2/bulk-jobs)، ضع callback_url في المستوى الأعلى خارج options.

استعلام غير متزامن مع 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
  }
}

عناوين الاستدعاء المحفوظة مقابل callback_url لكل طلب

توفّر Management API أيضًا عناوين استدعاء محفوظة تُدار عبر لوحة التحكم تحت /v2/delivery/webhooks (بمصادقة cookieSession + csrfToken) لحفظ وجهات قابلة لإعادة الاستخدام وإرسال حمولات اختبار عبر POST /v2/delivery/webhooks/{webhookId}/test. أما التكاملات البرمجية فيجب أن تمرّر callback_url مباشرةً في كل إرسال.

حمولات الأحداث والترويسات

تؤكد الإشعارات وصول المهمة إلى completed أو failed (أو نشر بيان Bulk). لا تحتوي الحمولات أبدًا على نتائج الاستعلام أو ملفات الوسائط أو مفتاح API الخاص بك. أزل التكرار باستخدام delivery_id (الذي يُرسل أيضًا في ترويسة X-Delivery-Id).

الحقلالمعنى
delivery_idمعرّف تسليم ثابت لإزالة التكرار المتكرر؛ يطابق ترويسة X-Delivery-Id.
idمعرّف المهمة أو مهمة Bulk. طابقه مع الإيصال المحفوظ عند الإرسال.
sourceمصدر البيانات المطلوب (مثل google_search أو youtube_download).
statusالحالة النهائية: completed أو failed للمهام غير المتزامنة والدفعات؛ وcompleted لمهام Bulk بعد نشر البيان.
linksروابط الحالة والنتائج المصادق عليها في Management 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"
    }
  ]
}
حدث إكمال 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.

أحداث Webhook غير موقّعة. لا تثق بعناوين URL الواردة في الحمولة تلقائيًا ولا تستدعِ مضيفين عشوائيين: طابق id وsource مع الإيصال المحفوظ، وتحقق من الحالة عبر GET /v2/jobs/{id} أو GET /v2/bulk-jobs/{bulkId} باستخدام X-API-Key، واحتفظ بالاستطلاع الدوري كخيار احتياطي.

مستقبل Webhook بسيط بلغة 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);