コンテンツへスキップ
JA
APIキーを取得する
ドキュメントを探す

API リファレンス

完了通知 Webhook

非同期・バッチ・Bulk ジョブの完了通知を受信し、重複排除および検証を行います。

このページの内容

callback_url を設定する

非同期クエリ、バッチエントリ、または Bulk ジョブの送信時に、ポート 443 の公開 HTTPS callback_url(最大 2,048 文字、認証情報やフラグメントなし)を指定します。通知を無効にするには callback_url を省略するか、null または空文字列を渡してください。

非同期およびバッチリクエスト(POST /v1/queries、POST /v1/queries/batch)では、params の外側となるクエリオブジェクトのトップレベルに callback_url を配置します。Bulk ジョブ(POST /v2/bulk-jobs)では、options の外側となるトップレベルに配置します。

callback_url 付きの非同期クエリ
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
callback_url 付きの Bulk ジョブ
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

保存済みコールバック URL とリクエストごとの callback_url

Management API はコンソール管理の保存済みコールバック URL 用エンドポイント /v2/delivery/webhooks(cookieSession + csrfToken)も提供しており、再利用可能な送信先の保存や POST /v2/delivery/webhooks/{webhookId}/test によるテスト送信が可能です。プログラムからの API 連携では、送信ごとに callback_url を直接指定してください。

イベントペイロードとヘッダー

通知はジョブが completed または failed に達したこと(あるいは Bulk マニフェストが公開されたこと)を知らせます。ペイロードにクエリ結果、メディアファイル、API キーは含まれません。delivery_id(X-Delivery-Id ヘッダーにも付与)を使って配信の重複を排除してください。

フィールド説明
delivery_id冪等な重複排除のための安定した配信 ID。X-Delivery-Id ヘッダーと一致します。
idジョブまたは Bulk ジョブの ID。送信時に保存したレシートと照合してください。
sourceリクエストされたデータソース(例:google_search や youtube_download)。
status終了状態:非同期/バッチは completed または failed、Bulk はマニフェスト公開後に completed。
links認証済みの Management API ステータスおよび結果リンク。結果を取得する前に必ず API 経由で確認してください。
非同期 / バッチ完了イベント
{
  "delivery_id": "dlv_01JEXAMPLE0000000000000000",
  "id": "job_01JEXAMPLE0000000000000000",
  "source": "google_search",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000/results",
      "method": "GET"
    }
  ]
}
Bulk 完了イベント
{
  "delivery_id": "dlv_01JEXAMPLE0000000000000001",
  "id": "bulk_01JEXAMPLE0000000000000000",
  "source": "youtube_metadata",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000",
      "method": "GET"
    },
    {
      "rel": "manifest",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000/manifest",
      "method": "GET"
    }
  ]
}

リトライ・検証・受信側の安全性

配信は初回を含め指数バックオフで合計最大 8 回試行されます。delivery_id を永続化したら速やかに 2xx 応答を返してください。

Webhook イベントには署名がありません。ペイロード内の URL を無条件に信頼したり任意のホストへアクセスしたりせず、id と source を保存済みレシートと照合し、X-API-Key で GET /v2/jobs/{id} または GET /v2/bulk-jobs/{bulkId} を呼び出して状態を確認し、フォールバックとしてポーリングを維持してください。

最小限の Node.js Webhook 受信サーバー
import http from "node:http";

const seen = new Set(); // Replace with durable database storage in production.

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/webhooks/flashdata") {
    res.writeHead(404).end();
    return;
  }
  const chunks = [];
  req.on("data", chunk => chunks.push(chunk));
  req.on("end", () => {
    const event = JSON.parse(Buffer.concat(chunks).toString("utf8"));
    const deliveryId = String(req.headers["x-delivery-id"] ?? event.delivery_id ?? "");
    if (!deliveryId || seen.has(deliveryId)) {
      res.writeHead(200).end("ok");
      return;
    }
    seen.add(deliveryId);
    // Queue background verification against https://api.flashdata.dev/v2/jobs/{id}
    // or /v2/bulk-jobs/{id} with X-API-Key; ignore unverified URLs in event.links.
    res.writeHead(200).end("accepted");
  });
}).listen(3000);