Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Dokumentacja API

Webhooki ukończenia

Odbieraj, deduplikuj i weryfikuj powiadomienia o zakończeniu zadań asynchronicznych, wsadowych i Bulk.

Na tej stronie

Konfiguracja callback_url

Podaj publiczny adres HTTPS callback_url na porcie 443 (do 2 048 znaków, bez poświadczeń i fragmentu URL) podczas wysyłania zapytań asynchronicznych, pozycji wsadowych lub zadań Bulk. Pomiń callback_url albo przekaż null lub pusty ciąg, aby wyłączyć powiadomienia.

W żądaniach asynchronicznych i wsadowych (POST /v1/queries oraz POST /v1/queries/batch) umieść callback_url na najwyższym poziomie obiektu zapytania, poza params. W zadaniach Bulk (POST /v2/bulk-jobs) umieść callback_url na najwyższym poziomie, poza options.

Zapytanie asynchroniczne z callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Zadanie Bulk z callback_url
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

Zapisane adresy callback a callback_url dla żądania

Management API udostępnia także zarządzane z konsoli zapisane adresy callback pod /v2/delivery/webhooks (cookieSession + csrfToken) do zapisywania wielokrotnego użytku miejsc docelowych i wysyłania testowych ładunków przez POST /v2/delivery/webhooks/{webhookId}/test. Integracje programistyczne powinny przekazywać callback_url bezpośrednio przy każdym zgłoszeniu.

Ładunki zdarzeń i nagłówki

Powiadomienia potwierdzają, że zadanie osiągnęło stan completed lub failed (albo że opublikowano manifest Bulk). Ładunki nigdy nie zawierają wyników zapytań, plików multimedialnych ani Twojego klucza API. Deduplikuj dostarczenia za pomocą delivery_id (wysyłanego także w nagłówku X-Delivery-Id).

PoleZnaczenie
delivery_idStały identyfikator dostarczenia do idempotentnej deduplikacji; odpowiada nagłówkowi X-Delivery-Id.
idIdentyfikator zadania lub zadania Bulk. Porównaj z potwierdzeniem zapisanym przy wysłaniu.
sourceŻądane źródło danych (na przykład google_search lub youtube_download).
statusStan końcowy: completed lub failed dla async/batch; completed dla Bulk po opublikowaniu manifestu.
linksUwierzytelnione linki statusu i wyników w Management API. Zawsze weryfikuj przez API przed pobraniem wyników.
Zdarzenie ukończenia async / batch
{
  "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"
    }
  ]
}
Zdarzenie ukończenia 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"
    }
  ]
}

Ponowne próby, weryfikacja i bezpieczeństwo odbiornika

Dostarczenie jest podejmowane łącznie do ośmiu razy, wliczając pierwszą próbę, z wykładniczym opóźnieniem. Zwróć odpowiedź 2xx niezwłocznie po zapisaniu delivery_id.

Zdarzenia webhook nie są podpisane. Nigdy nie ufaj bezkrytycznie adresom URL z ładunku ani nie odpytuj dowolnych hostów: dopasuj id i source do zapisanego potwierdzenia, zweryfikuj status przez GET /v2/jobs/{id} lub GET /v2/bulk-jobs/{bulkId} z nagłówkiem X-API-Key i zachowaj odpytywanie statusu jako rozwiązanie zapasowe.

Minimalny odbiornik webhooków w 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);