Skip to content
EN
Get API key
Browse documentation

API reference

Completion webhooks

Receive, deduplicate and verify async, batch and Bulk completion notifications.

On this page

Configure callback_url

Supply a public HTTPS callback_url on port 443 (up to 2,048 characters, without credentials or a URL fragment) when submitting async queries, batch entries, or Bulk jobs. Omit callback_url, or pass null or an empty string, to disable notifications.

For async and batch requests (POST /v1/queries and POST /v1/queries/batch), place callback_url on the top-level query object, outside params. For Bulk jobs (POST /v2/bulk-jobs), place callback_url at the top level, outside options.

Async query with callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Bulk job with callback_url
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

Saved callback URLs vs per-request callback_url

The Management API also exposes console-managed saved callback URLs under /v2/delivery/webhooks (cookieSession + csrfToken) for saving reusable destinations and sending sample test payloads via POST /v2/delivery/webhooks/{webhookId}/test. Programmatic API integrations should pass callback_url directly on each submission.

Event payloads and headers

Notifications confirm that a job reached completed or failed (or that a Bulk manifest was published). Payloads never contain query results, media files, or your API key. Deduplicate deliveries using delivery_id (also sent in the X-Delivery-Id header).

FieldMeaning
delivery_idStable delivery identifier for idempotent deduplication; matches the X-Delivery-Id header.
idJob or Bulk job identifier. Match against the receipt saved at submission.
sourceRequested data source (for example google_search or youtube_download).
statusTerminal state: completed or failed for async/batch; completed for Bulk after manifest publication.
linksAuthenticated Management API status and results links. Always verify via the API before fetching results.
Async / batch completion event
{
  "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 completion event
{
  "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"
    }
  ]
}

Retries, verification and receiver safety

Delivery tries up to eight times in total, including the first attempt, with exponential backoff. Return a 2xx response promptly after persisting delivery_id.

Webhook events are unsigned. Never trust payload URLs blindly or fetch arbitrary hosts: match id and source to your saved receipt, verify status via GET /v2/jobs/{id} or GET /v2/bulk-jobs/{bulkId} with X-API-Key, and keep status polling as a fallback.

Minimal Node.js webhook receiver
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);