Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Riferimento API

Webhook di completamento

Ricevi, deduplica e verifica le notifiche di completamento per job asincroni, batch e Bulk.

In questa pagina

Configura callback_url

Fornisci una callback_url HTTPS pubblica sulla porta 443 (fino a 2.048 caratteri, senza credenziali né frammenti URL) quando invii query asincrone, elementi batch o job Bulk. Ometti callback_url oppure passa null o una stringa vuota per disattivare le notifiche.

Per le richieste asincrone e batch (POST /v1/queries e POST /v1/queries/batch), inserisci callback_url al livello superiore dell’oggetto query, fuori da params. Per i job Bulk (POST /v2/bulk-jobs), inserisci callback_url al livello superiore, fuori da options.

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

URL di callback salvati vs callback_url per richiesta

La Management API espone anche URL di callback salvati gestiti dalla console su /v2/delivery/webhooks (cookieSession + csrfToken) per salvare destinazioni riutilizzabili e inviare payload di test tramite POST /v2/delivery/webhooks/{webhookId}/test. Le integrazioni API programmatiche devono passare callback_url direttamente in ogni invio.

Payload degli eventi e intestazioni

Le notifiche confermano che un job ha raggiunto lo stato completed o failed (oppure che il manifest Bulk è stato pubblicato). I payload non contengono mai risultati di query, file multimediali o la tua chiave API. Deduplica le consegne usando delivery_id (inviato anche nell’intestazione X-Delivery-Id).

CampoSignificato
delivery_idIdentificatore di consegna stabile per la deduplicazione idempotente; corrisponde all’intestazione X-Delivery-Id.
idIdentificatore del job o del job Bulk. Confrontalo con la ricevuta salvata all’invio.
sourceOrigine dati richiesta (ad esempio google_search o youtube_download).
statusStato finale: completed o failed per async/batch; completed per Bulk dopo la pubblicazione del manifest.
linksLink autenticati di stato e risultati della Management API. Verifica sempre tramite API prima di recuperare i risultati.
Evento di completamento asincrono / 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"
    }
  ]
}
Evento di completamento 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"
    }
  ]
}

Nuovi tentativi, verifica e sicurezza del ricevitore

La consegna viene tentata fino a otto volte in totale, incluso il primo tentativo, con backoff esponenziale. Restituisci rapidamente una risposta 2xx dopo aver salvato delivery_id.

Gli eventi webhook non sono firmati. Non fidarti mai ciecamente degli URL nel payload e non contattare host arbitrari: confronta id e source con la ricevuta salvata, verifica lo stato tramite GET /v2/jobs/{id} o GET /v2/bulk-jobs/{bulkId} con X-API-Key e mantieni il polling di stato come fallback.

Ricevitore webhook minimale in 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);