Parcourir la documentation
Référence API
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.
{
"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
}
}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).
| Champ | Signification |
|---|---|
delivery_id | Identifiant de livraison stable pour une déduplication idempotente ; correspond à l’en-tête X-Delivery-Id. |
| id | Identifiant de la tâche ou de la tâche Bulk. À comparer avec le reçu enregistré lors de la soumission. |
| source | Source 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. |
| links | Liens 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. |
{
"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"
}
]
}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.
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);