DEV Community

Cover image for Async AI Webhooks on Localhost: OpenAI Batch and Gemini’s Two Webhook Models
InstaTunnel
InstaTunnel

Posted on Originally published at instatunnel.my Fully Autonomous

Async AI Webhooks on Localhost: OpenAI Batch and Gemini’s Two Webhook Models

Batch jobs are expensive to debug. You submit thousands of prompts, wait hours, and your callback handler only sees real input when the job finishes. If the handler has a bug, the lazy fix is to run the batch again.

You shouldn’t have to. OpenAI and Google now both push completion events instead of making you poll. Google announced event-driven webhooks for the Gemini API on May 4, 2026. OpenAI delivers callbacks that follow the Standard Webhooks specification for batches, background responses, fine-tuning jobs and other events. This guide is about the job lifecycle. It covers how to receive these callbacks on localhost, how Gemini’s two configuration models differ, and why a batch success event gives you a pointer instead of results. It also shows how to iterate on your handler without paying for another batch.

(Signature failures behind a tunnel, such as re-serialized bodies, are a separate topic and are not covered in depth here.)

Why long-running AI jobs need webhooks

Polling works, but it wastes calls and adds latency. On OpenAI you poll GET /v1/batches/{batch_id}. On Gemini, Google’s launch post describes repeatedly calling GET on operations. Google frames the problem as agentic and high-volume work, such as Deep Research, long video generation, or thousands of prompts through the Batch API, where operations can take minutes or even hours.

The completion window is the key number. OpenAI’s Batch API currently accepts only a 24h completion window, and its docs promise that each batch completes within 24 hours, often sooner. Gemini’s event catalog describes batch.expired as a batch that wasn’t finished within a 24-hour timeframe. A callback can therefore arrive at any point inside that day. That is when your laptop is most likely to have changed networks, restarted or gone to sleep.

Two status notes before you build on this:

  • Gemini’s webhooks documentation labels the feature as preview, even though Google’s launch post says it is available to all Gemini API developers. Expect details to change and re-check the docs before you ship.
  • OpenAI’s Batch API gives a 50% cost discount versus synchronous APIs. That discount is also why re-running a failed batch because of a handler bug is such a tempting and wasteful habit.

OpenAI and Gemini webhooks at a glance

OpenAI Gemini API
Where configured Per project: dashboard (name, public URL, event types) or the webhooks API Static: WebhookService API. Dynamic: webhook_config on a request
Batch events batch.completed, batch.failed, batch.cancelled, batch.expired batch.succeeded, batch.failed, batch.cancelled, batch.expired
Other async events 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
Signing Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature); secret shown once at endpoint creation Static: Standard Webhooks HMAC, secret shown once. Dynamic: RS256 JWT in the Webhook-Signature header, verified against a JWKS
Payload style Thin: object, event id, type, created_at, data.id Thin: type, version, timestamp, data
Retries Non-2xx or no response within a few seconds is retried for up to 72 hours with exponential backoff; 3xx redirects are not followed Retried for 24 hours with exponential backoff; respond 2xx within a few seconds
Maturity Documented guide and API reference Marked preview in the docs

Three details matter immediately.

  1. The success event is named differently. It is batch.completed on OpenAI and batch.succeeded on Gemini. A shared handler keyed on the type string needs an explicit mapping.
  2. Both providers deliver at least once, so duplicates can happen. Use the webhook-id header as your idempotency key. OpenAI’s docs recommend this explicitly. Gemini’s documented payload example has no event ID in the body, so the header is the only reliable choice there.
  3. A “completed” OpenAI batch doesn’t promise every request succeeded. The batch object tracks request_counts (total, completed, failed) and separates output_file_id from error_file_id. A completed batch can still contain failed lines.

Gemini’s two webhook models: static vs dynamic

This is the part that genuinely differs from OpenAI, and the reason Gemini handlers are harder to test.

Static webhooks: register once, receive everything

Static webhooks are project-level endpoints created through the WebhookService API. They trigger for any matching event in the project. Beyond creating them, you can get, list, update and delete them, and rotate their signing secret.

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
Enter fullscreen mode Exit fullscreen mode

Static webhooks are signed with HMAC under the Standard Webhooks scheme. The signing secret is shown only at creation, and if you lose it you rotate rather than retrieve. Rotation lets you choose whether previous secrets are revoked immediately or after a 24-hour grace period (revocation_behavior="revoke_previous_secrets_after_h24" in the Python SDK). The grace period lets the old secret keep working while you deploy the new one.

Local-development gotcha: a static webhook covers the whole project. A dev endpoint registered in the same Google Cloud project as production will receive production events, and production will receive yours. Use a separate project and API key for development. OpenAI has the same shape: its webhook endpoints are configured per project, so use a separate project for dev there too.

Dynamic webhooks: per-job overrides

Dynamic webhooks are request-level overrides. You pass a webhook_config in the call that creates the job. Google’s launch post shows this for a batch:

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"},
        },
    },
)
Enter fullscreen mode Exit fullscreen mode

Four details are worth knowing:

  • uris is a list, and user_metadata is an arbitrary key-value object you attach to the job. The documented thin payload example doesn’t show user_metadata coming back in the delivery. Before you route on it, check a captured real delivery to see whether and where it appears.
  • For the Interactions API, background=True is required whenever webhook_config is set. Google’s Interactions examples also carry a comment that they only work with SDK versions newer than 2.0.0.
  • Dynamic webhooks use asymmetric signatures. Your listener reads a JWT from the Webhook-Signature header and verifies it against Google’s public keys (RS256).
  • Google’s docs are inconsistent about where those keys live. The prose links to https://www.googleapis.com/oauth2/v3/certs, while the sample code fetches https://generativelanguage.googleapis.com/.well-known/jwks.json. The samples also pass a placeholder audience value, with a comment suggesting something like your project client ID. Confirm the exact key URL and audience against the current docs before you enforce either.

A handler that supports both models therefore needs two verification paths, because a Standard Webhooks library will not verify the dynamic JWT. Google’s samples fetch the key set on every request. In production you should cache it and refetch when you see an unknown kid.

Which should you use?

Use static for things that should always happen: audit logging, a Slack notification, a data-sync job. Use dynamic when you want specific jobs routed to specific places, such as a worker queue per tenant, or one developer’s batch landing on that developer’s machine without touching shared project configuration. For local debugging, dynamic is often the safer choice. The callback target lives in the job, not in project state your teammates share.

The batch success payload is a pointer, not the result

Neither provider sends you the output. Google’s envelope is explicitly a “thin payload” model:

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

Google’s example uses a gs:// Cloud Storage-style URI, which is not an HTTPS link you can fetch with a plain GET. The docs don’t say how your handler should download it, so don’t hard-code assumptions. Capture a real delivery and see what your jobs actually return. Google’s own samples also check whether output_file_uri is present before using it, with a comment tying it to batch jobs created from an input file. Don’t assume the field exists on every batch.succeeded event.

The other Gemini batch events carry different data. batch.failed includes error_code and error_message, while batch.cancelled and batch.expired carry only the id.

OpenAI’s pattern is similar. The data object holds only the batch ID:

{
  "id": "evt_abc123",
  "type": "batch.completed",
  "created_at": 1719168000,
  "data": { "id": "batch_abc123" }
}
Enter fullscreen mode Exit fullscreen mode

To get results, you call the Batch API, read output_file_id from the batch object, and download it through the Files API. Read error_file_id for failed requests. Four details matter here:

  • Output lines may not match input order, so map results back with the custom_id on each line.
  • If a batch expires, completed requests’ responses are still made available in the output file. Unfinished requests land in the error file with a batch_expired error, and you’re charged for the completed ones. A handler for batch.expired should therefore still look for output.
  • Cancelling a batch moves it to cancelling first, which can take up to 10 minutes while in-flight requests finish. A batch.cancelled event is not instant.
  • By default, batch output and error files expire 30 days after creation. You can change this with output_expires_after (1 hour to 30 days) when creating the batch.

So the webhook is a notification, and the real work happens in a second step. That split is the key to cheap debugging, because you can test the two halves separately.

Debug the callback without re-running the batch

Here’s a workflow that avoids paying for a second batch.

1. Capture one real delivery. Submit a small batch, then record exactly what arrives: headers and raw body. A tiny Express recorder does it:

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

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

// Keep the raw body: signature verification needs the exact bytes
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);
Enter fullscreen mode Exit fullscreen mode

Respond 2xx quickly. Both providers retry if you don’t answer within a few seconds, so record first and process later. Fixtures contain job IDs and possibly output locations, so keep them out of version control.

2. Separate verification from handling. Structure your code as verify(request) -> event followed by handle(event). Then you can feed saved events straight to handle() and skip signature checks entirely. The verification helpers already exist. OpenAI’s SDKs provide client.webhooks.unwrap(body, headers). For Gemini static webhooks, Google’s samples use the standardwebhooks library. For dynamic ones you verify the JWT yourself.

This split matters most for Gemini dynamic webhooks. You can’t re-sign a saved delivery, because you don’t hold Google’s private key. A saved token may stop verifying, for example if it expires or Google rotates keys, and the docs don’t say how long tokens stay valid. Replaying the parsed event into handle() avoids the problem entirely.

3. Normalize event names at the boundary. Map each provider’s type strings to one internal vocabulary before your business logic sees them:

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",
}
Enter fullscreen mode Exit fullscreen mode

4. Mind the freshness window. Google’s best practices tell you to reject payloads whose webhook-timestamp is older than five minutes, to mitigate replay attacks. A saved fixture replayed an hour later should fail a correct handler. For static Gemini and OpenAI-style signatures, re-sign fixtures with a test secret and a fresh timestamp, or make the tolerance configurable in development only.

5. Stub the pointer fetch. Put a small output file on disk and swap your Files API or storage reader for a local one. Now the success event becomes a fast, offline test that needs no cloud credentials.

6. Test the sad paths. Save fixtures for batch.failed, batch.expired and batch.cancelled as well, since you rarely get to see these in real traffic. Include an OpenAI batch with a non-empty error_file_id. Also hand-write a duplicate delivery with the same webhook-id to confirm your idempotency check works.

7. Use provider test tools where they exist. OpenAI’s dashboard webhook settings page can trigger test events with sample data, and its API reference lists a “Test Webhook Endpoint” method. Gemini’s webhook docs don’t describe an equivalent, so your recorded fixtures do that job.

8. Reconcile with one poll. Retries are finite: 24 hours on Gemini, up to 72 on OpenAI. If your endpoint is down for longer than that, the event is gone, and a batch can itself legitimately take up to 24 hours. On startup, scan your job ledger for jobs still marked submitted and check their status with one GET. Treat webhooks as the fast path and polling as a safety net. Do this before the output files expire, which is 30 days by default on OpenAI.

Your ledger can be simple: job ID, provider, status (submitted, succeeded, failed, cancelled, expired) and the last webhook-id processed. Neither provider’s docs promise delivery ordering, so apply updates only if they move a job forward, never backward.

Where a stable tunnel subdomain helps

Localhost isn’t reachable by Google or OpenAI, so you need a public HTTPS URL. OpenAI’s own guide acknowledges this and suggests tools such as ngrok, or cloud development environments like Replit, GitHub Codespaces, Cloudflare Workers and v0. What matters for batch work is whether that URL stays the same.

  • OpenAI endpoints and static Gemini webhooks are registered once. If the URL changes every session, you’re back in the dashboard or the API updating it. A fixed hostname can be registered once and left alone.
  • Dynamic Gemini webhooks put the URL inside each job. You can bake a stable hostname into webhook_config.uris in your submission code, so every job you launch already points home.
  • Avoid redirects on the registered URL. OpenAI does not follow 3xx responses and treats them as failures, so register the final HTTPS URL, including the exact path.
  • Session length should match the job horizon. InstaTunnel’s README advertises a free tier with 24+ hour sessions, custom subdomains such as myapp.instatunnel.my, and three simultaneous tunnels. Its published Pro tier is $5/month. Check the current pricing page for limits before relying on any of this. A tunnel session that lasts as long as a 24-hour batch window doesn’t guarantee a single session covers the whole job. Provider retries mean a short reconnect shouldn’t lose the event, as long as you come back on the same address.
npm install -g instatunnel
instatunnel 3000 --subdomain my-app
# https://my-app.instatunnel.my -> localhost:3000
Enter fullscreen mode Exit fullscreen mode

One tunnel is enough if you route by path (/hooks/openai, /hooks/gemini-static, /hooks/gemini-dynamic). A separate tunnel per integration is optional, for example if you want separate logs. Either way, keep Gemini’s dev project separate from production so the static endpoint only receives your own events.

Checklist before you ship

  • Map event names explicitly: batch.completed (OpenAI) and batch.succeeded (Gemini).
  • Read the raw body before any JSON middleware touches it.
  • Return 2xx fast, then queue the real work.
  • Deduplicate on webhook-id, and keep dedupe records longer than the retry window (72 hours for OpenAI).
  • Check for failed lines in a “completed” OpenAI batch via error_file_id, and look for partial output on batch.expired.
  • Don’t assume output_file_uri is present on every Gemini event, and verify what your real deliveries contain.
  • Run two verifiers if you use both Gemini models, and cache the JWKS.
  • Don’t register URLs that redirect; OpenAI won’t follow them.
  • Add a reconciliation poll for jobs that outlive your endpoint’s downtime.

Frequently asked questions

Do Gemini webhooks work with the Batch API?

Yes. Batch is a main use case, with batch.succeeded, batch.failed, batch.cancelled and batch.expired events. Webhooks also cover Interactions and video generation.

Are Gemini webhooks generally available?

Google’s launch post says they’re available to all developers using the Gemini API, but the documentation currently marks the feature as preview. Re-check the docs before depending on specifics.

What’s the difference between static and dynamic Gemini webhooks?

Static webhooks are project-level endpoints created through the WebhookService API and signed with an HMAC secret. Dynamic webhooks are set per request via webhook_config and signed with a JWT you verify against Google’s public keys.

Does the webhook contain my batch results?

No. Gemini sends a pointer (such as the output_file_uri in Google’s example), and OpenAI sends only the batch ID, after which you retrieve the output file.

How long do providers keep retrying?

Google retries for 24 hours with exponential backoff. OpenAI retries for up to 72 hours with exponential backoff.

Can I test OpenAI webhooks without running a job?

Yes. The dashboard webhook settings page can send test events with sample data.

Will OpenAI follow a redirect on my webhook URL?

No. 3xx responses are treated as failures, so register the final destination URL.

Conclusion

Async AI callbacks are easy to receive and hard to debug because their inputs are expensive to reproduce. Capture one real delivery, separate verification from handling, stub the result fetch, and keep a polling sweep for anything that outlives your retry window. Then the batch only has to run once, and everything after that is a fixture.


Sources


Originally published at https://instatunnel.my/blog/async-ai-webhooks-on-localhost-openai-batch-and-geminis-two-webhook-models

Top comments (0)