Zum Hauptinhalt springen
Geben Sie bei einem Task webhook.url an, und querying.ai sendet das Ergebnis per POST dorthin, sobald der Task COMPLETED oder FAILED erreicht.

Zustellungs-Payload

Jede Zustellung ist ein POST mit Content-Type: application/json und diesem Body: Zum Beispiel ein abgeschlossener Perplexity-Task (Perplexity kostet 1 Credit):
Auch ein fehlgeschlagener Task wird zugestellt:
Die Preise pro Task-Typ finden Sie unter Credits und Limits.

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:
Eine Zustellung ist nur dann unsigniert, wenn der Task keinen API-Schlüssel hat, oder bei einem Batch, dessen API-Schlüssel vor mehr als 30 Tagen widerrufen wurde. Stammen alle Ihre Tasks von einem API-Schlüssel, lehnen Sie Anfragen ohne gültige Signatur ab.
Nachdem Sie einen Schlüssel rotiert haben, werden mit dem neuen Schlüssel eingereichte Tasks mit dem neuen Schlüssel signiert. Zustellungen für zuvor eingereichte Tasks werden weiterhin mit dem Schlüssel signiert, der sie eingereicht hat.

Wiederholungen

Geben Sie innerhalb von 30 Sekunden einen beliebigen 2xx 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 mit include.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 mit POST /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:
Das Ereignis ist mit dem API-Schlüssel des Batches signiert, seine 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.