メインコンテンツへスキップ
タスクに webhook.url を指定すると、タスクが COMPLETED または FAILED に達したときに querying.ai が結果をそこへPOSTします。

配信ペイロード

各配信は Content-Type: application/json の POST で、本文は次のとおりです。 完了した Perplexity タスクの例(Perplexity は1クレジット):
失敗したタスクも配信されます。
タスク種別ごとの料金はクレジットと上限に記載しています。

署名を検証する

APIキーで送信したタスクは、そのキーで署名されます。各配信には3つのヘッダーが付きます。 HMACの鍵は、タスクを送信したAPIキー(バッチの場合はバッチを作成したキー)のSHA-256ダイジェスト32バイトです。解析する前の生の本文に対して署名を計算し、定数時間で比較し、5分以内のタイムスタンプを受け入れてください。
署名のない配信になるのは、タスクにAPIキーがない場合か、APIキーが30日以上前に無効化されたバッチの場合だけです。作成するタスクがすべてAPIキーからのものなら、有効な署名のないリクエストは拒否してください。
キーをローテーションした後、新しいキーで送信したタスクは新しいキーで署名されます。それ以前に送信したタスクの配信は、引き続き送信時のキーで署名されます。

再試行

受信確認には30秒以内に任意の 2xx を返してください。それ以外のステータス、タイムアウト、接続エラーは失敗した試行とみなします。失敗した配信は2、4、8、16分後に再試行され、約30分で合計5回試行します。すべて同じ querying-webhook-id です。5回目に失敗すると配信は破棄されます。 リダイレクトには従いません。3xx は失敗した試行とみなします。 配信を拒否するときは、理由をレスポンス本文に入れてください。先頭 200 文字がステータスと一緒に保存され(例: HTTP 400: sources must not be empty)、ダッシュボードと失敗通知メールに表示されます。 配信はタスクとは別に実行されます。Webhookが届かなかったタスクも GET /v1/async/task/{id} では COMPLETED と表示されます。回収するには、非同期タスクで説明している24時間の期間内にポーリングしてください。

HTMLページ

include.html を付けたタスクも同じJSONボディを配信します。ページ本体はボディに含まれません。response.html.url がページへのリンクで、そこからダウンロードします。ダウンロードにAPIキーは不要で、リクエストの Accept-Encoding が許可していればBrotliまたはgzipで圧縮され、圧縮方式は Content-Encoding に示されます。HTMLページを参照してください。

URLのルール

webhook.url は送信時に確認されます。ルールに反するURLは、webhook.url フィールドの 400 VALIDATION_ERROR で拒否されます。 配信時には、ホストが公開アドレスにのみ解決される必要があり、そうでなければ試行は失敗します。接続は確認したアドレスに対して行われます。

安全なハンドラーを書く

1

検証してからすばやく受信確認する

署名を確認し、ペイロードを永続的に保存してから 200 を返してください。解析やデータベース書き込みはその後で行います。遅いハンドラーは30秒のタイムアウトに達し、再試行を招きます。
2

重複を除く

配信は少なくとも1回(at least once)です。処理済みの querying-webhook-id のメッセージはスキップするか、task.idempotencyKey で照合して書き込みを冪等にしてください。
3

statusで分岐する

task.status を明示的に確認してください。失敗したタスクも response.error 付きのWebhookを配信します。

バッチ完了イベント

POST /v1/batches で webhook.url を指定して作成したバッチは、各タスクの結果を上記と同じくそのURLに送信し、すべての項目が終了したら完了イベントを1回POSTします。
このイベントはバッチのAPIキーで署名され、querying-webhook-id は batch_<batch id> で、同じ再試行スケジュールに従います。このイベントを送るのは、createdAt から30日以内、バッチを読み取れる間だけです。

次のステップ

非同期タスク

ステータス、ポーリング、保持期間。

バッチとグリッド

数千件のタスクに1つのWebhook URL。