Обзор документации
Справочник 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.
{
"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. Программные 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"
}
]
}{
"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);