Перейти к содержимому
RU
Ключ 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);