webhook.url an, und querying.ai sendet das Ergebnis per POST dorthin, sobald der Task COMPLETED oder FAILED erreicht.
Zustellungs-Payload
Jede Zustellung ist einPOST mit Content-Type: application/json und diesem Body:
Zum Beispiel ein abgeschlossener Perplexity-Task (Perplexity kostet 1 Credit):
Signatur prüfen
Mit einem API-Schlüssel eingereichte Tasks werden mit diesem Schlüssel signiert. Jede Zustellung trägt drei Header:
Der HMAC-Schlüssel ist der 32-Byte-SHA-256-Digest des API-Schlüssels, der den Task eingereicht hat (bei einem Batch der Schlüssel, der den Batch erstellt hat). Berechnen Sie die Signatur über den rohen Body, bevor Sie ihn parsen, vergleichen Sie in konstanter Zeit und akzeptieren Sie Zeitstempel innerhalb von fünf Minuten:
Wiederholungen
Geben Sie innerhalb von 30 Sekunden einen beliebigen2xx zurück, um zu bestätigen. Jeder andere Status, ein Timeout oder ein Verbindungsfehler gilt als fehlgeschlagener Versuch. Fehlgeschlagene Zustellungen werden nach 2, 4, 8 und 16 Minuten wiederholt: insgesamt fünf Versuche über etwa 30 Minuten, jeweils mit derselben querying-webhook-id. Nach dem fünften Fehlschlag wird die Zustellung aufgegeben.
Weiterleitungen werden nicht verfolgt: Ein 3xx zählt als fehlgeschlagener Versuch.
Wenn Sie eine Zustellung ablehnen, schreiben Sie den Grund in den Antworttext. Die ersten 200 Zeichen werden mit dem Status gespeichert, zum Beispiel HTTP 400: sources must not be empty, und erscheinen im Dashboard und in der Fehler-E-Mail.
Die Zustellung läuft getrennt vom Task. Ein Task, dessen Webhook nie ankommt, zeigt in GET /v1/async/task/{id} weiterhin COMPLETED. Um das Ergebnis nachzuholen, pollen Sie innerhalb des 24-Stunden-Fensters, das unter Asynchrone Tasks beschrieben ist.
HTML-Seiten
Ein Task mitinclude.html stellt denselben JSON-Body zu. Die Seite selbst ist nicht darin enthalten: response.html.url verweist auf die Seite, und Sie laden sie von dort herunter. Der Download braucht keinen API-Schlüssel und kommt mit Brotli oder gzip komprimiert, benannt in Content-Encoding, wenn das Accept-Encoding Ihrer Anfrage es erlaubt. Siehe HTML-Seiten.
URL-Regeln
webhook.url wird beim Einreichen geprüft. Eine URL, die gegen eine Regel verstößt, wird mit 400 VALIDATION_ERROR für das Feld webhook.url abgelehnt.
Zum Zeitpunkt der Zustellung darf der Host nur auf öffentliche Adressen auflösen, sonst schlägt der Versuch fehl. Die Verbindung geht an die geprüfte Adresse.
Einen sicheren Handler schreiben
1
Prüfen, dann schnell bestätigen
Prüfen Sie die Signatur, speichern Sie den Payload dauerhaft und geben Sie
200 zurück. Parsen und Datenbankschreibvorgänge erledigen Sie danach, damit ein langsamer Handler nicht in das 30-Sekunden-Timeout läuft und eine Wiederholung auslöst.2
Deduplizieren
Die Zustellung erfolgt mindestens einmal. Überspringen Sie Nachrichten, deren
querying-webhook-id Sie bereits verarbeitet haben, oder gleichen Sie über task.idempotencyKey ab und machen Sie den Schreibvorgang idempotent.3
Nach Status verzweigen
Prüfen Sie
task.status explizit. Auch ein fehlgeschlagener Task stellt einen Webhook zu, mit response.error.Batch-Abschlussereignis
Ein mitPOST /v1/batches und einer webhook.url erstellter Batch sendet das Ergebnis jedes Tasks wie oben an diese URL und danach ein Abschlussereignis, sobald alle Einträge fertig sind:
querying-webhook-id ist batch_<batch id>, und es folgt demselben Wiederholungsplan. Es wird nur innerhalb von 30 Tagen ab dem createdAt des Batches gesendet, solange der Batch lesbar ist.
Nächste Schritte
Asynchrone Tasks
Status, Polling und Aufbewahrung.
Batches und Raster
Eine Webhook-URL für Tausende Tasks.