Passer au contenu principal
Fournissez 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 un POST avec Content-Type: application/json et ce corps : Par exemple, une tâche Perplexity terminée (Perplexity coûte 1 crédit) :
Une tâche échouée est aussi livrée :
Les prix par type de tâche figurent dans Crédits et limites.

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 :
Une livraison n’est non signée que si la tâche n’a pas de clé d’API, ou pour un lot dont la clé d’API a été révoquée plus de 30 jours auparavant. Si toutes vos tâches sont créées avec une clé d’API, refusez les requêtes sans signature valide.
Après la rotation d’une clé, les tâches soumises avec la nouvelle clé sont signées avec la nouvelle clé. Les livraisons des tâches soumises auparavant restent signées avec la clé qui les a soumises.

Nouvelles tentatives

Renvoyez n’importe quel 2xx 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 avec include.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éé avec POST /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 :
L’événement est signé avec la clé d’API du lot, son 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.