Explorar documentación
Referencia de la API
Recibe, deduplica y verifica notificaciones de finalización para tareas asíncronas, por lotes y Bulk.
En esta página
Configurar callback_url
Proporciona una callback_url HTTPS pública en el puerto 443 (hasta 2.048 caracteres, sin credenciales ni fragmento de URL) al enviar consultas asíncronas, elementos de lote o trabajos Bulk. Omite callback_url o envía null o una cadena vacía para desactivar notificaciones.
En solicitudes asíncronas y por lotes (POST /v1/queries y POST /v1/queries/batch), coloca callback_url en el nivel superior del objeto de consulta, fuera de params. En trabajos Bulk (POST /v2/bulk-jobs), coloca callback_url en el nivel superior, fuera de 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
}
}URLs de callback guardadas frente a callback_url por solicitud
La Management API también expone URLs de callback guardadas desde la consola en /v2/delivery/webhooks (cookieSession + csrfToken) para guardar destinos reutilizables y enviar payloads de prueba con POST /v2/delivery/webhooks/{webhookId}/test. Las integraciones programáticas deben pasar callback_url directamente en cada envío.
Payloads de eventos y encabezados
Las notificaciones confirman que un trabajo alcanzó completed o failed (o que se publicó el manifiesto Bulk). Los payloads nunca contienen resultados, archivos multimedia ni tu clave API. Deduplica las entregas usando delivery_id (también enviado en el encabezado X-Delivery-Id).
| Campo | Significado |
|---|---|
delivery_id | Identificador de entrega estable para deduplicación idempotente; coincide con el encabezado X-Delivery-Id. |
| id | Identificador del trabajo o trabajo Bulk. Compáralo con el recibo guardado al enviar. |
| source | Fuente de datos solicitada (por ejemplo, google_search o youtube_download). |
| status | Estado terminal: completed o failed para async/batch; completed para Bulk tras publicar el manifiesto. |
| links | Enlaces autenticados de estado y resultados de la Management API. Verifica siempre mediante la API antes de obtener resultados. |
{
"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"
}
]
}Reintentos, verificación y seguridad del receptor
La entrega se intenta hasta ocho veces en total, incluido el primer intento, con retroceso exponencial. Devuelve una respuesta 2xx con prontitud tras guardar delivery_id.
Los eventos webhook no están firmados. Nunca confíes ciegamente en las URLs del payload ni consultes hosts arbitrarios: compara id y source con tu recibo guardado, verifica el estado mediante GET /v2/jobs/{id} o GET /v2/bulk-jobs/{bulkId} con X-API-Key y mantén el sondeo de estado como respaldo.
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);