InstaTunnel
Navigation menu o kirikae
API
14 min read
38 views

localhost上での非同期AIウェブフック: OpenAI バッチと Gemini の2つのウェブフックモデル

localhost上で OpenAI バッチと Gemini のウェブフックを再実行せずにデバッグします。Gemini の静的と動的ウェブフックモデル、HMAC、JWKS、バッチペイロードについて学びましょう。

IT
InstaTunnel Team
Published by the InstaTunnel team | Editorial policy
localhost上での非同期AIウェブフック: OpenAI バッチと Gemini の2つのウェブフックモデル

Quick answer

localhost上の非同期AIウェブフック: OpenAI バッチと Gemini(2026): webhook testing answer

For local webhook testing, run your app locally, expose it with a public HTTPS tunnel, and paste the stable callback URL into the provider dashboard.

How do I test webhooks on localhost?

Start your local server, open a public HTTPS tunnel to that port, configure the provider webhook URL, and inspect events in your local logs.

Why does a stable webhook URL matter?

Stable URLs prevent provider dashboards from needing manual callback updates every time you restart a tunnel.

バッチ処理のデバッグはコストが高い。数千件のプロンプトを送信し、数時間待ち、コールバックハンドラはジョブが完了したときに初めて実入力を受け取ります。ハンドラにバグがある場合、怠慢な解決策はバッチを再度実行することです。

それは避けるべきです。OpenAI と Google は現在、ポーリングを要求する代わりに完了イベントを送出します。Google は Gemini API のイベント駆動型ウェブフックを 2026年5月4日に発表しました。OpenAI は、バッチ、バックグラウンドのレスポンス、ファインチューニングジョブ、その他のイベントに対して Standard Webhooks 仕様に従うコールバックを提供します。本ガイドは ジョブライフサイクル についてです。localhost でこれらのコールバックを受け取る方法、Gemini の二つの設定モデルの違い、そしてバッチの成功イベントが結果ではなく手掛かりを返す理由を扱います。さらに、別のバッチを支払うことなくハンドラを改善する方法も示します。

(署名検証の失敗がトンネルの背後にあるような、再シリアライズされた本文などは別のトピックであり、ここでは詳しくは扱いません。)

なぜ長時間実行されるAIジョブにはウェブフックが必要なのか

ポーリングは機能しますが、呼び出しを浪費し、遅延を増やします。OpenAI では GET /v1/batches/{batch_id} をポーリングします。Gemini では Google のローンチ投稿が、操作に対して繰り返し GET を呼び出すことを説明しています。Google はこの問題をエージェント性が高く高ボリュームの作業、例えば Deep Research、長時間の動画生成、または Batch API を介した何千ものプロンプトのようなケースとして捉え、オペレーションは数分または数時間かかることがあります。

完了ウィンドウは鍵となる数値です。OpenAI の Batch API は現在 24h の完了ウィンドウのみを受け付け、ドキュメントは各バッチが 24 時間以内に完了することを約束し、通常はそれより早く完了します。Gemini のイベントカタログでは batch.expired を、24時間の範囲内で完了しなかったバッチとして説明しています。コールバックはその日 の任意の時点で到着する可能性があり、そのときはノートパソコンのネットワークが変わっていたり、再起動されたり、スリープしている可能性が最も高くなります。

これを前提に構築する前の2つのステータスノート:

  • Gemini のウェブフックのドキュメントはこの機能を プレビュー としてラベル付けしますが、Google のローンチ投稿では Gemini API のすべての開発者が利用可能とされています。出荷前に詳細が変わる可能性があるため、出荷前にドキュメントを再確認してください。
  • OpenAI の Batch API は同期 API に対する 50% のコスト割引を提供します。この割引は、ハンドラのバグにより失敗したバッチを再実行することが魅力的で無駄な習慣になる理由にもなります。

OpenAI と Gemini のウェブフックを一目で見る

OpenAI Gemini API
設定場所 プロジェクトごと: ダッシュボード(名前、公開URL、イベントタイプ)またはウェブフックAPI 静的: WebhookService API。動的: リクエスト上の webhook_config
バッチイベント batch.completed, batch.failed, batch.cancelled, batch.expired batch.succeeded, batch.failed, batch.cancelled, batch.expired
その他の非同期イベント response.completed/failed/cancelled/incomplete, fine_tuning.job.succeeded/failed/cancelled, eval.run.succeeded/failed/canceled, realtime.call.incoming interaction.requires_action/completed/failed/cancelled, video.generated
署名 標準 Webhooks ヘッダ(webhook-id、webhook-timestamp、webhook-signature); 組織時に一度だけ秘密が表示 静的: 標準 Webhooks HMAC、秘密は作成時に一度表示。動的: Webhook-Signature ヘッダ内の RS256 JWT を JWKS に対して検証
ペイロードの形式 Thin: object, event id, type, created_at, data.id Thin: type, version, timestamp, data
リトライ Non-2xx または 応答なしは、最大 72 時間、指数バックオフで再試行 24 時間、指数バックオフで再試行。数秒以内に 2xx で応答
成熟度 ドキュメント化されたガイドと API リファレンス ドキュメント内でプレビューと表示

3 つの点がすぐに重要です。

  1. 成功イベントは名前が異なります。 OpenAI では batch.completed、Gemini では batch.succeeded です。type 文字列をキーにした共用ハンドラには明示的なマッピングが必要です。
  2. 両方の提供元は少なくとも一度は配信します。重複が発生します。webhook-id ヘッダを冪等性キーとして使用してください。OpenAI のドキュメントはこれを明示的に推奨します。Gemini の文書のペイロード例には本体にイベントIDが含まれていないため、ヘッダが信頼できる唯一の選択肢です。
  3. 「completed」 OpenAI バッチはすべてのリクエストが成功することを保証しません。 バッチオブジェクトは request_counts(総数、完了、失敗)を追跡し、output_file_id と error_file_id を分離します。完了したバッチでも失敗した行を含むことがあります。

Gemini の2つのウェブフックモデル: 静的 vs 動的

これは OpenAI とは genuinely 異なる点であり、Gemini のハンドラをテストするのが難しくなる理由です。

静的ウェブフック: 一度登録して全てを受け取る

静的ウェブフックは WebhookService API を介して作成されるプロジェクトレベルのエンドポイントです。プロジェクト内の一致するイベントが発生するとトリガーされます。作成後は取得、一覧表示、更新、削除、署名秘密の回転が可能です。

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

webhook = client.webhooks.create(
    name="MyBatchWebhook",
    subscribed_events=["batch.succeeded", "batch.failed"],
    uri="https://my-api.com/gemini-callback",
)

# The signing secret is returned only once. Store it securely.
webhook_secret = webhook.new_signing_secret

静的ウェブフックは Standard Webhooks の HMAC で署名されます。署名秘密は作成時にしか表示されず、紛失した場合は回転させるのみです。回転により以前の秘密を直ちに取り消すか、24時間の猶予期間後に取り消すかを選択できます(revocation_behavior="revoke_previous_secrets_after_h24" の Python SDK)。猶予期間中は旧秘密を使い続けられます。

ローカル開発の注意点: 静的ウェブフックはプロジェクト全体をカバーします。 production と同じ Google Cloud プロジェクトに開発用エンドポイントを登録した場合、本番イベントを受け取り、本番もあなたの開発エンドポイントのイベントを受け取ることになります。開発には別のプロジェクトと API キーを使ってください。OpenAI も同様で、ウェブフックエンドポイントはプロジェクトごとに設定されるため、開発用にも別プロジェクトを使ってください。

動的ウェブフック: ジョブごとの上書き

動的ウェブフックはリクエストレベルのオーバーライドです。ジョブ作成時の呼び出しに webhook_config を渡します。Google のローンチ投稿はバッチに対してこれを示しています:

from google import genai

client = genai.Client()

file_batch_job = client.batches.create(
    model="<your-model>",
    src=inline_requests,
    config={
        "display_name": "My Setup",
        "webhook_config": {
            "uris": ["https://my-api.com/gemini-webhook-dynamic"],
            "user_metadata": {"job_group": "nightly-eval", "priority": "high"},
        },
    },
)

4つの点を抑えると役立ちます。

  • uris はリストで、user_metadata はジョブに付与する任意のキー-値オブジェクトです。文書化された薄いペイロードの例には、user_metadata が配信に戻ってくる様子は示されていません。ルーティングを設計する前に、実際のデリバリーをキャプチャして、どこに現れるかを確認してください。
  • Interactions API では、webhook_config が設定されている場合は background=True が必須です。Google の Interactions の例には、SDK バージョンが 2.0.0 以降でのみ動作するとコメントも付いています。
  • 動的ウェブフックは非対称署名を使用します。リスナーは Webhook-Signature ヘッダから JWT を読み取り、Google の公開鍵(RS256)に対して検証します。
  • Google のドキュメントは、それらの鍵がどこに格納されているかについて一貫性がありません。本文は https://www.googleapis.com/oauth2/v3/certs へのリンクを、サンプルコードは https://generativelanguage.googleapis.com/.well-known/jwks.json を取得します。サンプルにはプレースホルダーの audience 値も渡され、プロジェクトのクライアントIDのようなものを推奨するコメントがあります。現在のドキュメントを確認して、どちらを適用するかを決定してください。

両方のモデルをサポートするハンドラは、二つの検証パスを必要とします。標準 Webhooks ライブラリは動的 JWT を検証しないためです。Google のサンプルはキーセットを毎回取得します。本番環境ではキャッシュして、未知の kid を見つけた場合に再取得してください。

どちらを使うべきですか?

常時発生させたい処理には 静的 を使用します:監査ログ、Slack 通知、データ同期ジョブなど。特定のジョブを特定の場所へルーティングしたい場合は 動的 を使います。例えばテナントごとのワーカークエ‑や、1人の開発者のバッチをその開発者のマシンへ直接落とす場合などです。ローカルデバッグには、動的が安全な選択肢であることが多いです。コールバックのターゲットはジョブ内にあり、チームメイトと共有されるプロジェクトの状態にはありません。

バッチの成功ペイロードはポインタであり、結果そのものではない

どちらの提供者も出力を送ってはくれません。Google のエンベロープは明示的に“薄いペイロード”モデルです:

{
  "type": "batch.succeeded",
  "version": "v1",
  "timestamp": "2026-01-22T12:00:00Z",
  "data": {
    "id": "batch_123456",
    "output_file_uri": "gs://my-bucket/results.jsonl"
  }
}

Google の例では gs:// の Cloud Storage スタイルの URI が使われ、HTTPS のリンクを単純に GET で取得することはできません。ドキュメントはハンドラがどうダウンロードすべきかを示していないため、前提を固定せず、実際のデリバリーをキャプチャしてジョブが実際に何を返すかを確認してください。Google の自分のサンプルでも output_file_uri が存在するかを使用前に確認しており、入力ファイルから作成されたバッチジョブに関連付けられたコメントがあります。すべての batch.succeeded イベントでこのフィールドが必ずあるとは限りません。

他の Gemini バッチイベントは異なるデータを含みます。batch.failed には error_code と error_message が含まれ、batch.cancelled と batch.expired には id のみが含まれます。

OpenAI のパターンも同様です。data オブジェクトにはバッチIDのみが含まれます:

{
  "id": "evt_abc123",
  "type": "batch.completed",
  "created_at": 1719168000,
  "data": { "id": "batch_abc123" }
}

結果を取得するには Batch API を呼び出し、バッチオブジェクトから output_file_id を読み取り、Files API を介してダウンロードします。失敗したリクエストのためには error_file_id を読みます。ここで4点が重要です:

  • 出力行は入力順と一致しないことがあるため、各行の custom_id で結果を対応づけます。
  • バッチが期限切れになると、完了したリクエストのレスポンスは出力ファイルに引き続き公開されます。未完成のリクエストは batch_expired エラーとともにエラーファイルに入り、完了したものに対しては料金が課金されます。batch.expired のハンドラはしたがって出力を探すべきです。
  • バッチをキャンセルすると、まず cancelling に移行します。これは飛行中のリクエストが終了するまで最大で10分かかることがあります。batch.cancelled イベントは即時には発生しません。
  • デフォルトでは、バッチの出力ファイルとエラーファイルは作成後 30 日で有効期限切れになります。output_expires_after(1 時間〜 30 日)を設定して変更できます。

したがってウェブフックは通知であり、実際の作業は二つ目のステップで行われます。この分離が、安価なデバッグの鍵です。二つの半分を別々にテストできるからです。

バッチを再実行せずにコールバックをデバッグする

以下は二番目のバッチを支払わずに済むワークフローです。

1. 実デリバリーを1件キャプチャ。 小さなバッチを送信し、到着した内容を正確に記録します: ヘッダと生データ。小さな Express レコーダーがそれを行います:

import express from "express";
import fs from "node:fs";

const app = express();
fs.mkdirSync("fixtures", { recursive: true });

// 署名検証には正確なバイト列が必要なので生データを保持
app.use(express.text({ type: "application/json" }));

app.post("/hooks/:provider", (req, res) => {
  fs.writeFileSync(
    `fixtures/${req.params.provider}-${Date.now()}.json`,
    JSON.stringify({ headers: req.headers, body: req.body }, null, 2)
  );
  res.sendStatus(200);
});

app.listen(3000);

2xx を素早く返します。どちらのプロバイダも、数秒以内に応答がないとリトライします。まずは記録して、後で処理してください。フィクスチャにはジョブIDや出力場所が含まれることがあり、版本管理には含めないでください。

2. 検証と処理を分離。 コードを verify(request) -> event の形で構造し、続けて handle(event) を実装します。保存したイベントをそのまま handle() に渡して署名検証を完全にスキップできます。検証用ヘルパーはすでに存在します。OpenAI の SDK は client.webhooks.unwrap(body, headers) を提供します。Gemini の静的ウェブフックでは Google のサンプルが standardwebhooks ライブラリを使用します。動的な場合は自分で JWT を検証します。

この分割は特に Gemini の動的ウェブフックで重要です。保存したデリバリを再署名することはできません。保存 token が有効期限切れになったり、Google が鍵を回転させたりする場合、検証が失敗する可能性があります。解析済みイベントを handle() に再投入することで問題を回避できます。

3. 境界でイベント名を正規化。 各プロバイダのタイプ文字列を、ビジネスロジックに現れる前に一つの内部語彙へマッピングします。

TERMINAL_STATUS = {
    ("openai", "batch.completed"): "succeeded",
    ("openai", "batch.failed"): "failed",
    ("openai", "batch.cancelled"): "cancelled",
    ("openai", "batch.expired"): "expired",
    ("gemini", "batch.succeeded"): "succeeded",
    ("gemini", "batch.failed"): "failed",
    ("gemini", "batch.cancelled"): "cancelled",
    ("gemini", "batch.expired"): "expired",
}

4. 新鮮さのウィンドウを意識。 Google のベストプラクティスは、webhook-timestamp が現在時刻から5分より古いペイロードを拒否することです。保存済みのフィクスチャをリプレイしても、正しいハンドラは失敗します。静的 Gemini と OpenAI 風の署名については、フィクスチャに新しいタイムスタンプとテスト用秘密で再署名してください。開発時のみ許容範囲を設定可能にしてください。

5. ポインタ取得をスタブ。 小さな出力ファイルをディスク上に置き、Files API やストレージリーダーをローカルのものに置換します。これで成功イベントは高速なオフラインテストとなり、クラウド認証情報は不要です。

6. 誤った経路をテスト。 batch.failed、batch.expired、batch.cancelled のフィクスチャも保存してください。本番の実 traffic では滅多にこれらを見られません。空でない error_file_id を含む OpenAI バッチを含め、同じ webhook-id を用いた重複デリバリを手書きで作成して冪等性チェックが機能することを確認してください。

7. 可能な場合はプロバイダのテストツールを使用。 OpenAI のダッシュボードの webhook 設定ページはサンプルデータでテストイベントを発生させることができ、API リファレンスには “Test Webhook Endpoint” メソッドが掲載されています。Gemini のウェブフックドキュメントには同等の機能の記載はなく、記録済みのフィクスチャがその役割を果たします。

8. 1つのポーリングで整合性を取る。 リトライは有限です。Gemini は 24 時間、OpenAI は最大 72 時間です。エンドポイントがこれより長く落ちている場合、イベントは消え、バッチ自体も最大 24 時間かかることがあります。起動時には、ジョブ台帳をスキャンしてまだ submitted と表示されているジョブを探し、1 回の GET で状況を確認します。ウェブフックを高速経路として扱い、ポーリングをセーフティネットとします。出力ファイルの有効期限が切れる前、OpenAI ではデフォルトで 30 日です。

あなたの台帳はシンプルで構いません。ジョブID、プロバイダ、ステータス(submitted、succeeded、failed、cancelled、expired)と、処理済みの最後の webhook-id を記録します。どちらのプロバイダのドキュメントも配信順序を保証していませんので、ジョブが前進した場合のみ更新し、後退させないでください。

安定したトンネルのサブドメインが役立つ場所

localhost は Google や OpenAI から到達されません。そのため公開 HTTPS URL が必要です。OpenAI 自身のガイドもこれを認め、ngrok のようなツールや Replit、GitHub Codespaces、Cloudflare Workers、以前の v0 などのクラウド開発環境を推奨しています。バッチ作業で重要なのは、その URL が同じままであることです。

  • OpenAI のエンドポイントと静的 Gemini ウェブフックは一度登録されます。 URL が毎セッションで変わる場合、ダッシュボードに戻るか API がそれを更新します。固定のホスト名は一度登録してそのままにしておけます。
  • 動的 Gemini ウェブフックは URL を各ジョブの中に入れます。 提出コードの webhook_config.uris に安定したホスト名を組み込むことで、起動するすべてのジョブがすでにホームへ向くようになります。
  • 登録済みURLのリダイレクトを避ける。 OpenAI は 3xx のレスポンスを追従しません。最終の HTTPS URL(正確なパスを含む)を登録してください。
  • セッションの長さはジョブの horizon に合わせる。 InstaTunnel の README は 24 時間以上のセッション、my-app.instatunnel.my のようなカスタムサブドメイン、3つの同時トンネルを謳っています。Pro プランは月額 $5。現在の価格ページで制限を確認してください。24時間バッチのウィンドウと同等の長さのトンネルセッションがジョブ全体を1セッションでカバーするとは限りません。プロバイダのリトライは、同じアドレスで戻ってくればイベントを失わないことを意味します。 npm install -g instatunnel instatunnel 3000 --subdomain my-app # https://my-app.instatunnel.my -> localhost:3000

パスでルーティングする場合は1つのトンネルで十分です(/hooks/openai、/hooks/gemini-static、/hooks/gemini-dynamic)。統合ごとに別のトンネルを設定するのも任意です。いずれにせよ、静的エンドポイントがあなた自身のイベントのみを受け取るよう、開発用の Gemini プロジェクトを本番環境と分離してください。

出荷前チェックリスト

  • イベント名を明示的に対応付ける:batch.completed(OpenAI)と batch.succeeded(Gemini)
  • 生データをまず読む: JSON ミドルウェアが触れる前に
  • 迅速に 2xx を返し、その後で実作業をキューへ
  • webhook-id で重複排除し、リトライウィンドウを超えたレコードも保持(OpenAI は 72 時間)
  • error_file_id で失敗行を確認し、batch.expired で部分出力を探す
  • すべての Gemini イベントで output_file_uri が必ずあるとは限らないことを理解し、実デリバリーを検証
  • Gemini の2モデルを両方使う場合は2つの検証を実行し、JWKS をキャッシュ
  • リダイレクトするURLは登録しない
  • エンドポイントのダウンタイムを超えるジョブには照合ポーリングを追加

よくある質問

Gemini ウェブフックは Batch API と動作しますか?
はい。Batch は主要なユースケースで、batch.succeeded、batch.failed、batch.cancelled、batch.expired イベントを含みます。ウェブフックは Interactions や動画生成もカバーします。

Gemini ウェブフックは一般提供されていますか?
Google のローンチ投稿は Gemini API のすべての開発者が利用可能としていますが、現時点のドキュメントはこの機能をプレビューとしてマークしています。具体的な仕様に依存する前に再度ドキュメントを確認してください。

静的と動的 Gemini ウェブフックの違いは?
静的ウェブフックは WebhookService API を介して作成され、HMAC 秘密で署名されます。動的ウェブフックはリクエストごとに webhook_config で設定され、Google の公開鍵で検証する JWT 署名となります。

ウェブフックには私のバッチ結果が含まれますか?
いいえ。Gemini は output_file_uri のようなポインタを送信します。OpenAI はバッチIDのみを送信し、その後出力ファイルを取得します。

プロバイダは再試行をどのくらい続けますか?
Google は 24 時間、指数バックオフで再試行します。OpenAI は最大 72 時間、指数バックオフで再試行します。

OpenAI のウェブフックをジョブを実行せずにテストできますか?
はい。ダッシュボードの webhook 設定ページからサンプルデータを使ったテストイベントを送信できます。

OpenAI はウェブフックURLのリダイレクトを追従しますか?
いいえ。3xx のレスポンスは失敗として扱われるため、最終の宛先URLを登録してください。

結論

非同期 AI コールバックは受信自体は容易ですが、入力を再現するコストが高いためデバッグは難しいです。実デリバリーを1件だけキャプチャし、検証と処理を分離し、結果取得をスタブし、リトライウィンドウを超えるものにはポーリングを併用します。そうすればバッチは一度だけ実行され、その後はすべてフィクスチャになります。


出典

Continue from this article into the most relevant product guides and workflows.

Related Topics

#async AI webhooks#AI webhooks localhost#OpenAI batch webhooks#Gemini API webhooks#Gemini webhooks#OpenAI webhooks#webhook localhost testing#test webhooks locally#debug webhooks localhost#localhost tunneling#localhost tunnel#expose localhost to internet#ngrok alternative#stable webhook URL#static subdomain tunnel#persistent tunnel URL#OpenAI Batch API#Gemini Batch API#batch job callbacks#long-running job callbacks#async job webhooks#background responses OpenAI#OpenAI fine-tuning webhooks#Standard Webhooks#Standard Webhooks specification#webhook signature verification#HMAC webhook verification#JWKS webhook verification#JWT webhook authentication#Gemini event-driven webhooks#Gemini static webhooks#Gemini dynamic webhooks#project-level webhook endpoint#per-request webhook override#webhook job lifecycle#batch completion webhook#batch success payload#Google Cloud Storage bucket webhook#webhook payload debugging#webhook replay#webhook retry handling#idempotent webhook handler#webhook event handling#webhook development#webhook testing tools#webhook best practices#AI API integration#LLM webhooks#LLM batch processing#generative AI API#AI developer tools#developer infrastructure#cloud-native development#DevOps tools#API callbacks#event-driven architecture#asynchronous API design#polling vs webhooks#webhook security#secure tunnel for webhooks

Keep building with InstaTunnel

Read the docs for implementation details or compare plans before you ship.

Share this article

More InstaTunnel Insights

Discover more tutorials, tips, and updates to help you build better with localhost tunneling.

Browse All Articles