Saltar al contenido
ES
Obtener clave API
Explorar documentación

Referencia de la API

Webhooks de finalización

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.

Consulta asíncrona con callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Trabajo Bulk con callback_url
{
  "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).

CampoSignificado
delivery_idIdentificador de entrega estable para deduplicación idempotente; coincide con el encabezado X-Delivery-Id.
idIdentificador del trabajo o trabajo Bulk. Compáralo con el recibo guardado al enviar.
sourceFuente de datos solicitada (por ejemplo, google_search o youtube_download).
statusEstado terminal: completed o failed para async/batch; completed para Bulk tras publicar el manifiesto.
linksEnlaces autenticados de estado y resultados de la Management API. Verifica siempre mediante la API antes de obtener resultados.
Evento de finalización asíncrono / por lotes
{
  "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"
    }
  ]
}
Evento de finalización 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"
    }
  ]
}

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.

Receptor webhook mínimo en 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);