Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Référence API

Webhooks de fin de traitement

Recevez, dédupliquez et vérifiez les notifications de fin pour les requêtes asynchrones, par lots et Bulk.

Sur cette page

Configurer callback_url

Indiquez une callback_url HTTPS publique sur le port 443 (jusqu’à 2 048 caractères, sans identifiants ni fragment d’URL) lors de la soumission de requêtes asynchrones, par lots ou Bulk. Omettez callback_url, ou passez null ou une chaîne vide, pour désactiver les notifications.

Pour les requêtes asynchrones et par lots (POST /v1/queries et POST /v1/queries/batch), placez callback_url au niveau supérieur de l’objet de requête, en dehors de params. Pour les tâches Bulk (POST /v2/bulk-jobs), placez callback_url au niveau supérieur, en dehors de options.

Requête asynchrone avec callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Tâche Bulk avec callback_url
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

URL de rappel enregistrées vs callback_url par requête

L’API de gestion expose également des URL de rappel enregistrées depuis la console sous /v2/delivery/webhooks (cookieSession + csrfToken) pour sauvegarder des destinations réutilisables et envoyer des charges utiles de test via POST /v2/delivery/webhooks/{webhookId}/test. Les intégrations programmatiques doivent passer callback_url directement lors de chaque soumission.

Charges utiles d’événements et en-têtes

Les notifications confirment qu’une tâche a atteint completed ou failed (ou qu’un manifeste Bulk a été publié). Les charges utiles ne contiennent jamais de résultats, de fichiers multimédias ni votre clé API. Dédupliquez les livraisons à l’aide de delivery_id (également envoyé dans l’en-tête X-Delivery-Id).

ChampSignification
delivery_idIdentifiant de livraison stable pour une déduplication idempotente ; correspond à l’en-tête X-Delivery-Id.
idIdentifiant de la tâche ou de la tâche Bulk. À comparer avec le reçu enregistré lors de la soumission.
sourceSource de données demandée (par exemple google_search ou youtube_download).
statusÉtat final : completed ou failed pour async/batch ; completed pour Bulk après publication du manifeste.
linksLiens authentifiés d’état et de résultats de l’API de gestion. Vérifiez toujours via l’API avant de récupérer les résultats.
Événement de fin asynchrone / par lots
{
  "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"
    }
  ]
}
Événement de fin 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"
    }
  ]
}

Tentatives, vérification et sécurité du récepteur

La livraison est tentée jusqu’à huit fois au total, première tentative comprise, avec un délai exponentiel. Renvoyez rapidement une réponse 2xx après avoir enregistré delivery_id.

Les événements webhook ne sont pas signés. Ne faites jamais aveuglément confiance aux URL de la charge utile et n’appelez pas d’hôtes arbitraires : comparez id et source à votre reçu enregistré, vérifiez le statut via GET /v2/jobs/{id} ou GET /v2/bulk-jobs/{bulkId} avec X-API-Key, et conservez le polling comme solution de repli.

Récepteur webhook minimal en 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);