Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Довідник API

Вебхуки завершення

Отримуйте, дедуплікуйте та перевіряйте сповіщення про завершення асинхронних, пакетних і Bulk-завдань.

На цій сторінці

Налаштування callback_url

Вкажіть публічний HTTPS-адрес callback_url на порту 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
  }
}

Збережені URL зворотного виклику проти callback_url у запиті

Management API також надає керовані з консолі збережені URL зворотного виклику за адресою /v2/delivery/webhooks (cookieSession + csrfToken) для збереження багаторазових адрес і надсилання тестових подій через POST /v2/delivery/webhooks/{webhookId}/test. Програмні інтеграції API мають передавати 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. Завжди перевіряйте через 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.

Події вебхуків не підписуються. Ніколи не довіряйте 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);