Przeglądaj dokumentację
Dokumentacja API
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.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://example.com/webhooks/flashdata"
}{
"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).
| Pole | Znaczenie |
|---|---|
delivery_id | Stały identyfikator dostarczenia do idempotentnej deduplikacji; odpowiada nagłówkowi X-Delivery-Id. |
| id | Identyfikator 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). |
| status | Stan końcowy: completed lub failed dla async/batch; completed dla Bulk po opublikowaniu manifestu. |
| links | Uwierzytelnione linki statusu i wyników w Management API. Zawsze weryfikuj przez API przed pobraniem wyników. |
{
"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"
}
]
}{
"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.
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);