Skip to main content
タスクに webhook.url を指定すると、タスクが終了状態(COMPLETED または FAILED)に達したときに 結果をそこへPOSTします。

配信ペイロード

Content-Type: application/json で次の本文をPOSTします。
object
必須
送信時に受け取ったものと同じタスクメタデータです。終了 status を持ち、送信した idempotencyKey も返されます。
object
必須
エンジンごとのクレジットコストです。Perplexity は 2、ChatGPT は 3 といった具合です(エンジンにより 1–3クレジット)。タスクが失敗した場合 creditsCharged は 0 です。常にゼロを返す送信・ポーリングの レスポンスと違い、このフィールドはゼロ以外の値を持ちます。
object
必須
エンジン固有の結果です。エンジンを参照してください。失敗したタスクでは、エンジンの 結果の代わりに { "error": "<reason>" } が入ります。
失敗したタスクも配信されます。

再試行

受信確認には任意の 2xx を返してください。それ以外はタイムアウトを含めてすべて失敗とみなし、 指数バックオフで再試行します。 5回目の試行の後、配信は破棄されログに記録されます。参照できるデッドレターキューはありません。タスクAPIで 結果を取得するには、24時間の公開ポーリング期間内にポーリングしてください。この期間は元のレコードの保存期間を 定めるものではありません。 各試行のリクエストタイムアウトは30秒です。
タスクから見ると配信は送りっぱなしです。完了したもののWebhookを配信できなかったタスクも、 GET /v1/async/task/{id} では COMPLETED と表示されます。ステータスは通知ではなくエンジンの処理を表します。

安全なハンドラーを書く

1

すばやく受信確認する

ペイロードを永続的にキューへ入れたら、すぐに 200 を返してください。解析やデータベース書き込みは その後で行います。遅いハンドラーは30秒のタイムアウトを使い切り、不要な再試行を招きます。
2

idempotencyKeyで重複を除く

再試行があるため、ハンドラーが同じタスクを複数回受け取るのは正常です。task.idempotencyKey (または task.id)で照合し、書き込みを冪等にしてください。
3

有無ではなくstatusで分岐する

task.status === "FAILED" を明示的に確認してください。失敗したタスクもWebhookを配信します。
Webhookリクエストには署名も共有シークレットもありません。エンドポイントが公開されている場合は、 ペイロードを信頼せず、推測されにくいURLパスを使うか、ネットワークレベルの制限の背後にハンドラーを置いてください。