Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

API-Referenz

Abschluss-Webhooks

Empfangen, deduplizieren und verifizieren Sie Abschlussbenachrichtigungen für Async-, Batch- und Bulk-Jobs.

Auf dieser Seite

callback_url konfigurieren

Geben Sie beim Einreichen von Async-Abfragen, Batch-Einträgen oder Bulk-Jobs eine öffentliche HTTPS-callback_url auf Port 443 an (bis zu 2.048 Zeichen, ohne Zugangsdaten oder URL-Fragment). Lassen Sie callback_url weg oder übergeben Sie null bzw. eine leere Zeichenfolge, um Benachrichtigungen zu deaktivieren.

Platzieren Sie callback_url bei Async- und Batch-Anfragen (POST /v1/queries und POST /v1/queries/batch) auf oberster Ebene des Query-Objekts außerhalb von params. Bei Bulk-Jobs (POST /v2/bulk-jobs) gehört callback_url auf die oberste Ebene außerhalb von options.

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

Gespeicherte Callback-URLs vs. callback_url pro Anfrage

Die Management API bietet außerdem über die Konsole verwaltete gespeicherte Callback-URLs unter /v2/delivery/webhooks (cookieSession + csrfToken), um wiederverwendbare Ziele zu speichern und über POST /v2/delivery/webhooks/{webhookId}/test Test-Payloads zu senden. Programmatische API-Integrationen sollten callback_url direkt bei jeder Übermittlung angeben.

Event-Payloads und Header

Benachrichtigungen bestätigen, dass ein Job completed oder failed erreicht hat (oder ein Bulk-Manifest veröffentlicht wurde). Payloads enthalten niemals Abfrageergebnisse, Mediendateien oder Ihren API-Schlüssel. Deduplizieren Sie Zustellungen über delivery_id (auch im Header X-Delivery-Id gesendet).

FeldBedeutung
delivery_idStabile Zustellungs-ID für idempotente Deduplizierung; entspricht dem Header X-Delivery-Id.
idJob- oder Bulk-Job-ID. Mit der beim Einreichen gespeicherten Quittung abgleichen.
sourceAngeforderte Datenquelle (z. B. google_search oder youtube_download).
statusEndzustand: completed oder failed für Async/Batch; completed für Bulk nach Veröffentlichung des Manifests.
linksAuthentifizierte Status- und Ergebnis-Links der Management API. Vor dem Abrufen der Ergebnisse stets über die API verifizieren.
Async-/Batch-Abschlussereignis
{
  "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-Abschlussereignis
{
  "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"
    }
  ]
}

Wiederholungen, Verifizierung und Empfängersicherheit

Die Zustellung erfolgt mit exponentiellem Backoff insgesamt bis zu achtmal, einschließlich des ersten Versuchs. Geben Sie nach dem Speichern von delivery_id umgehend eine 2xx-Antwort zurück.

Webhook-Ereignisse sind unsigniert. Vertrauen Sie Payload-URLs niemals blind und rufen Sie keine beliebigen Hosts ab: Gleichen Sie id und source mit Ihrer gespeicherten Quittung ab, prüfen Sie den Status per GET /v2/jobs/{id} oder GET /v2/bulk-jobs/{bulkId} mit X-API-Key und behalten Sie Status-Polling als Fallback bei.

Minimaler Node.js-Webhook-Empfänger
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);