webhook.url を指定すると、タスクが COMPLETED または FAILED に達したときに querying.ai が結果をそこへPOSTします。
配信ペイロード
各配信はContent-Type: application/json の POST で、本文は次のとおりです。
完了した Perplexity タスクの例(Perplexity は1クレジット):
署名を検証する
APIキーで送信したタスクは、そのキーで署名されます。各配信には3つのヘッダーが付きます。
HMACの鍵は、タスクを送信したAPIキー(バッチの場合はバッチを作成したキー)のSHA-256ダイジェスト32バイトです。解析する前の生の本文に対して署名を計算し、定数時間で比較し、5分以内のタイムスタンプを受け入れてください。
再試行
受信確認には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します。
querying-webhook-id は batch_<batch id> で、同じ再試行スケジュールに従います。このイベントを送るのは、createdAt から30日以内、バッチを読み取れる間だけです。
次のステップ
非同期タスク
ステータス、ポーリング、保持期間。
バッチとグリッド
数千件のタスクに1つのWebhook URL。