Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

API-referentie

Voltooiingswebhooks

Ontvang, ontdubbel en verifieer voltooiingsmeldingen voor async-, batch- en Bulk-taken.

Op deze pagina

callback_url configureren

Geef een openbare HTTPS-callback_url op poort 443 op (tot 2.048 tekens, zonder inloggegevens of URL-fragment) bij het indienen van async-queries, batchitems of Bulk-taken. Laat callback_url weg of geef null of een lege tekenreeks door om meldingen uit te schakelen.

Plaats callback_url bij async- en batchverzoeken (POST /v1/queries en POST /v1/queries/batch) op het hoogste niveau van het query-object, buiten params. Plaats callback_url bij Bulk-taken (POST /v2/bulk-jobs) op het hoogste niveau, buiten options.

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

Opgeslagen callback-URL’s vs. callback_url per verzoek

De Management API biedt ook via de console beheerde opgeslagen callback-URL’s onder /v2/delivery/webhooks (cookieSession + csrfToken) om herbruikbare bestemmingen op te slaan en testpayloads te sturen via POST /v2/delivery/webhooks/{webhookId}/test. Programmatische API-integraties kunnen callback_url het beste direct bij elke aanvraag meegeven.

Eventpayloads en headers

Meldingen bevestigen dat een taak completed of failed heeft bereikt (of dat een Bulk-manifest is gepubliceerd). Payloads bevatten nooit queryresultaten, mediabestanden of uw API-sleutel. Ontdubbel bezorgingen via delivery_id (ook meegestuurd in de header X-Delivery-Id).

VeldBetekenis
delivery_idStabiele bezorgings-ID voor idempotente ontdubbeling; komt overeen met de header X-Delivery-Id.
idTaak- of Bulk-taak-ID. Vergelijk met het ontvangstbewijs dat bij het indienen is opgeslagen.
sourceOpgevraagde gegevensbron (bijvoorbeeld google_search of youtube_download).
statusEindstatus: completed of failed voor async/batch; completed voor Bulk na publicatie van het manifest.
linksGeauthenticeerde status- en resultaatlinks van de Management API. Verifieer altijd via de API voordat u resultaten ophaalt.
Async- / batch-voltooiingsevent
{
  "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-voltooiingsevent
{
  "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"
    }
  ]
}

Her pogingen, verificatie en ontvangerbeveiliging

De bezorging wordt met exponentiële backoff in totaal tot acht keer geprobeerd, inclusief de eerste poging. Retourneer snel een 2xx-respons nadat u delivery_id hebt opgeslagen.

Webhook-events zijn niet ondertekend. Vertrouw payload-URL’s nooit blindelings en roep geen willekeurige hosts aan: vergelijk id en source met uw opgeslagen ontvangstbewijs, verifieer de status via GET /v2/jobs/{id} of GET /v2/bulk-jobs/{bulkId} met X-API-Key en behoud statuspolling als terugvaloptie.

Minimale Node.js-webhookontvanger
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);