webhook.url sur une tâche et querying.ai y envoie le résultat en POST quand la tâche atteint COMPLETED ou FAILED.
Charge utile de livraison
Chaque livraison est unPOST avec Content-Type: application/json et ce corps :
Par exemple, une tâche Perplexity terminée (Perplexity coûte 1 crédit) :
Vérifier la signature
Les tâches soumises avec une clé d’API sont signées avec cette clé. Chaque livraison porte trois en-têtes :
La clé HMAC est le condensat SHA-256 de 32 octets de la clé d’API qui a soumis la tâche (pour un lot, la clé qui a créé le lot). Calculez la signature sur le corps brut avant de l’analyser, comparez en temps constant et acceptez les horodatages à cinq minutes près :
Nouvelles tentatives
Renvoyez n’importe quel2xx sous 30 secondes pour accuser réception. Tout autre statut, un timeout ou une erreur de connexion compte comme une tentative échouée. Les livraisons échouées sont retentées après 2, 4, 8 et 16 minutes : cinq tentatives au total sur environ 30 minutes, chacune avec le même querying-webhook-id. Après le cinquième échec, la livraison est abandonnée.
Les redirections ne sont pas suivies : un 3xx compte comme une tentative échouée.
Si vous refusez une livraison, indiquez la raison dans le corps de la réponse. Les 200 premiers caractères sont conservés avec le statut, par exemple HTTP 400: sources must not be empty, et apparaissent dans le tableau de bord et dans l’e-mail d’échec.
La livraison est indépendante de la tâche. Une tâche dont le webhook n’arrive jamais reste COMPLETED sur GET /v1/async/task/{id}. Pour récupérer le résultat, interrogez la tâche pendant la fenêtre de 24 heures décrite dans Tâches asynchrones.
Pages HTML
Une tâche envoyée avecinclude.html livre le même corps JSON. La page elle-même n’y figure pas : response.html.url pointe vers la page, et vous la téléchargez à cette adresse. Le téléchargement ne demande aucune clé d’API et arrive compressé en Brotli ou en gzip, indiqué dans Content-Encoding, quand l’Accept-Encoding de votre requête le permet. Consultez Pages HTML.
Règles des URL
webhook.url est vérifiée à la soumission. Une URL qui enfreint une règle est refusée avec 400 VALIDATION_ERROR sur le champ webhook.url.
Au moment de la livraison, l’hôte doit se résoudre uniquement en adresses publiques, sinon la tentative échoue. La connexion se fait vers l’adresse vérifiée.
Écrire un handler sûr
1
Vérifier, puis accuser réception vite
Vérifiez la signature, stockez la charge utile de façon durable et renvoyez
200. Faites l’analyse et les écritures en base ensuite, pour qu’un handler lent n’atteigne pas le timeout de 30 secondes et ne provoque pas de nouvelle tentative.2
Dédupliquer
La livraison se fait au moins une fois. Ignorez un message dont vous avez déjà traité le
querying-webhook-id, ou rapprochez sur task.idempotencyKey et rendez l’écriture idempotente.3
Brancher sur le statut
Vérifiez explicitement
task.status. Une tâche échouée livre aussi un webhook, avec response.error.Événement de fin de lot
Un lot créé avecPOST /v1/batches et un webhook.url envoie le résultat de chaque tâche à cette URL comme ci-dessus, puis publie un événement de fin quand tous les éléments sont terminés :
querying-webhook-id est batch_<batch id>, et il suit le même calendrier de nouvelles tentatives. Il est envoyé uniquement dans les 30 jours suivant le createdAt du lot, tant que le lot est lisible.
Étapes suivantes
Tâches asynchrones
Statuts, polling et conservation.
Lots et grilles
Une seule URL de webhook pour des milliers de tâches.