InstaTunnel
Abrir menu de navegacion
API
14 min read
37 views

Webhooks de IA asíncronos en Localhost: Batch de OpenAI y los dos modelos de webhook de Gemini

Depura Batch de OpenAI y webhooks de Gemini en localhost sin volver a ejecutar trabajos. Aprende los modelos de webhook estáticos y dinámicos de Gemini, HMAC, JWKS y payloads de batch.

IT
InstaTunnel Team
Published by the InstaTunnel team | Editorial policy
Webhooks de IA asíncronos en Localhost: Batch de OpenAI y los dos modelos de webhook de Gemini

Quick answer

Webhooks de IA asíncronos en Localhost: Batch de OpenAI y 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.

Los trabajos Batch son costosos de depurar. Envías miles de prompts, esperas horas, y tu manejador de callbacks solo ve la entrada real cuando el trabajo termina. Si el manejador tiene un error, la solución perezosa es volver a ejecutar el batch.

No deberías tener que hacerlo. OpenAI y Google ahora envían eventos de finalización en lugar de hacerte sondear repetidamente. Google anunció webhooks impulsados por eventos para la Gemini API el 4 de mayo de 2026. OpenAI entrega callbacks que siguen la especificación de Webhooks Estándar para lotes, respuestas en segundo plano, trabajos de fine-tuning y otros eventos. Esta guía trata sobre el ciclo de vida del trabajo. Cubre cómo recibir estos callbacks en Localhost, cómo difieren los dos modelos de configuración de Gemini y por qué un evento de éxito de batch te da una referencia en lugar de resultados. También muestra cómo iterar en tu manejador sin pagar por otro Batch.

(Las fallas de firma detrás de un túnel, como cuerpos re-serializados, son un tema separado y no se abordan en profundidad aquí.)

Por qué los trabajos de IA de larga duración necesitan webhooks

El sondeo funciona, pero genera llamadas innecesarias y añade latencia. En OpenAI haces sondeos con GET /v1/batches/{batch_id}. En Gemini, la publicación de lanzamiento de Google describe llamar repetidamente a GET sobre las operaciones. Google enmarca el problema como trabajo de alto volumen y con agencia, como Deep Research, generación de video de larga duración o miles de prompts a través de la Batch API, donde las operaciones pueden tardar minutos u horas.

La ventana de finalización es la cifra clave. La Batch API de OpenAI actualmente admite solo una ventana de finalización de 24h, y su documentación promete que cada batch se completa dentro de 24 horas, a menudo antes. El catálogo de eventos de Gemini describe batch.expired como un batch que no se terminó dentro de un plazo de 24 horas. Por lo tanto, un callback puede llegar en cualquier punto dentro de ese día. Ese es el momento en que tu portátil probablemente cambió de red, se reinició o entró en modo de suspensión.

Dos notas de estado antes de basarte en esto:

  • La documentación de Gemini Webhooks etiqueta la función como preview, aunque la publicación de lanzamiento de Google dice que está disponible para todos los desarrolladores de Gemini API. Espera cambios y vuelve a revisar la documentación antes de desplegar.
  • La Batch API de OpenAI ofrece un descuento del 50% frente a APIs síncronas. Ese descuento es también la razón por la que volver a ejecutar un batch fallido por un fallo del manejador es un hábito tan tentador y derrochador.

Webhooks de OpenAI y Gemini, a simple vista

OpenAI Gemini API
Dónde se configuran Por proyecto: panel de control (nombre, URL pública, tipos de evento) o la API de webhooks Estático: API WebhookService. Dinámico: webhook_config en una solicitud
Eventos de Batch batch.completed, batch.failed, batch.cancelled, batch.expired batch.succeeded, batch.failed, batch.cancelled, batch.expired
Otros eventos asíncronos 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
Firmado Encabezados de Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature); secreto mostrado una sola vez en la creación del endpoint Estático: HMAC estándar de Webhooks, secreto mostrado una vez. Dinámico: JWT RS256 en el encabezado Webhook-Signature, verificado contra un JWKS
Formato de payload Delgado: object, id del evento, type, created_at, data.id Delgado: type, version, timestamp, data
Reintentos No-2xx o sin respuesta en unos segundos se reintentan hasta 72 horas con backoff exponencial; no se siguen redirecciones 3xx Reintentos durante 24 horas con backoff exponencial; responde 2xx en unos segundos
Madurez Guía documentada y referencia de la API Marcada como preview en la documentación

Tres detalles importan de inmediato.

  1. El evento de éxito tiene un nombre distinto. Es batch.completed en OpenAI y batch.succeeded en Gemini. Un manejador compartido indexado por la cadena type necesita un mapeo explícito.
  2. Ambos proveedores entregan al menos una vez, por lo que pueden ocurrir duplicados. Usa el encabezado webhook-id como clave de idempotencia. La documentación de OpenAI recomienda esto explícitamente. El payload documentado de Gemini no trae un ID de evento en el cuerpo, por lo que el encabezado es la única opción confiable allí.
  3. Un batch de OpenAI “completado” no garantiza que todas las solicitudes hayan tenido éxito. El objeto batch registra request_counts (total, completed, failed) y separa output_file_id de error_file_id. Un batch completado puede seguir conteniendo líneas con error.

Los dos modelos de webhook de Gemini: estáticos vs dinámicos

Esta es la parte que verdaderamente difiere de OpenAI, y la razón por la que los manejadores de Gemini son más difíciles de probar.

Webhooks estáticos: registrar una vez, recibir todo

Los webhooks estáticos son endpoints a nivel de proyecto creados a través de la API de WebhookService. Se activan para cualquier evento coincidente en el proyecto. Además de crearlos, puedes obtenerlos, listarlos, actualizarlos y eliminarlos, y rotar su secreto de firma.

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

Static webhooks están firmados con HMAC bajo el esquema Standard Webhooks. El secreto de firma se muestra solo al crearlo, y si lo pierdes lo rotas en lugar de recuperarlo. Rotation te permite elegir si los secretos anteriores se revocan de inmediato o después de una gracia de 24 horas (revocation_behavior="revoke_previous_secrets_after_h24" en el Python SDK). El periodo de gracia permite que el secreto viejo siga funcionando mientras implementas el nuevo.

Local-development gotcha: un webhook estático cubre todo el proyecto. Un endpoint de desarrollo registrado en el mismo proyecto de Google Cloud que producción recibirá eventos de producción, y producción recibirá los tuyos. Usa un proyecto separado y una API key para desarrollo. OpenAI tiene la misma forma: sus endpoints de webhook se configuran por proyecto, así que usa un proyecto separado para desarrollo también.

Webhooks dinámicos: sobrescrituras a nivel de trabajo

Los webhooks dinámicos son sobrescrituras a nivel de solicitud. Pasas un webhook_config en la llamada que crea el trabajo. La publicación de lanzamiento de Google muestra esto para un batch:

from google import genai

client = genai.Client()

file_batch_job = client.batches.create(
    model="<tu-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"},
        },
    },
)

Cuatro detalles son importantes:

  • uris es una lista, y user_metadata es un objeto clave-valor arbitrario que adjuntas al trabajo. El ejemplo de payload delgado documentado no muestra que user_metadata regrese en la entrega. Antes de enrutarlo, verifica una entrega real capturada para ver si aparece y dónde.
  • Para la Interactions API, background=True es obligatorio cada vez que se establece webhook_config. Los ejemplos de Interactions de Google también llevan un comentario de que solo funcionan con versiones de SDK superiores a 2.0.0.
  • Los webhooks dinámicos usan firmas asimétricas. Tu listener lee un JWT desde el encabezado Webhook-Signature y lo verifica contra las claves públicas de Google (RS256).
  • Los documentos de Google son inconsistentes sobre dónde viven esas claves. El texto enlaza a https://www.googleapis.com/oauth2/v3/certs, mientras que el código de ejemplo obtiene https://generativelanguage.googleapis.com/.well-known/jwks.json. Los ejemplos también pasan un valor de audience de marcador, con un comentario que sugiere algo como tu ID de cliente del proyecto. Confirma la URL exacta de la clave y el audience según la documentación vigente antes de aplicar cualquiera de ellas.

Un manejador que soporte ambos modelos necesita dos rutas de verificación, porque una biblioteca de Standard Webhooks no verificará el JWT dinámico. Los ejemplos de Google obtienen el conjunto de claves en cada solicitud. En producción deberías almacenarlo en caché y volver a obtenerlo cuando veas un kid desconocido.

¿Cuál deberías usar?

Usa static para cosas que deben ocurrir siempre: registro de auditoría, una notificación de Slack, un trabajo de sincronización de datos. Usa dynamic cuando quieras dirigir trabajos específicos a lugares concretos, como una cola de trabajadores por inquilino, o un batch de un desarrollador que llegue a la máquina de ese desarrollador sin tocar la configuración de proyecto compartido. Para depuración local, lo dinámico suele ser la opción más segura. El objetivo de callback vive en el trabajo, no en el estado del proyecto que comparten tus compañeros.

El payload de éxito del batch es un puntero, no el resultado

Ninguno de los dos proveedores te envía la salida. El envoltorio de Google es explícitamente un modelo de “payload delgado”:

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

El ejemplo de Google usa un URI estilo gs:// de Cloud Storage, que no es un enlace HTTPS que puedas obtener con un simple GET. Los documentos no dicen cómo debe descargarlo tu manejador, así que no hagas suposiciones codificadas. Captura una entrega real y observa qué devuelven realmente tus trabajos. Los propios ejemplos de Google también verifican si output_file_uri está presente antes de usarlo, con un comentario que lo vincula a trabajos batch creados a partir de un archivo de entrada. No asumas que el campo exista en cada evento batch.succeeded.

Los otros eventos de batch de Gemini llevan datos diferentes. batch.failed incluye error_code e error_message, mientras que batch.cancelled y batch.expired llevan solo el id.

El patrón de OpenAI es similar. El objeto data solo contiene el ID del batch:

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

Para obtener resultados, llamas a la Batch API, lees output_file_id desde el objeto batch y lo descargas a través de la Files API. Lee error_file_id para las solicitudes fallidas. Cuatro detalles importan aquí:

  • Las líneas de salida pueden no coincidir con el orden de entrada, así que mapea los resultados de vuelta con el custom_id en cada línea.
  • Si un batch expira, las respuestas de las solicitudes completadas siguen disponibles en el archivo de salida. Las solicitudes sin terminar quedan en el archivo de errores con un error batch_expired, y se te cobra por las que se completaron. Un manejador para batch.expired debería seguir buscando la salida.
  • Cancelar un batch lo mueve a cancelling primero, lo cual puede tardar hasta 10 minutos mientras las peticiones en vuelo terminan. Un evento batch.cancelled no es instantáneo.
  • Por defecto, la salida y los archivos de error del batch expiran 30 días después de la creación. Puedes cambiar esto con output_expires_after (1 hora a 30 días) al crear el batch.

Así que el webhook es una notificación, y el trabajo real ocurre en un segundo paso. Ese desglose es la clave para depurar de forma económica, porque puedes probar las dos mitades por separado.

Depura el callback sin volver a ejecutar el batch

Aquí tienes un flujo de trabajo que evita pagar por un segundo batch.

1. Captura una entrega real. Envía un batch pequeño, luego registra exactamente lo que llega: encabezados y cuerpo crudo. Un pequeño grabador Express lo hace:

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

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

// Guarda el cuerpo crudo: la verificación de firma necesita exactamente los 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);

Responde rápidamente con 2xx. Ambos proveedores reintentan si no respondes en unos segundos, así que primero registra y luego procesa. Los fixtures contienen IDs de trabajo y, posiblemente, ubicaciones de salida, así que mantenlos fuera del control de versiones.

2. Separa verificación de manejo. Estructura tu código como verify(request) -> event seguido de handle(event). Así puedes alimentar eventos guardados directamente a handle() y omitir por completo las verificaciones de firma. Los ayudantes de verificación ya existen. Los SDK de OpenAI proporcionan client.webhooks.unwrap(body, headers). Para webhooks estáticos de Gemini, los ejemplos de Google usan la biblioteca standardwebhooks. Para los dinámicos, verifica tú mismo el JWT.

Este desglose importa más para los webhooks dinámicos de Gemini. No puedes volver a firmar una entrega guardada, porque no posees la clave privada de Google. Un token guardado puede dejar de verificarse, por ejemplo si expira o Google rota las claves, y la documentación no dice cuánto tiempo siguen siendo válidos. Reproducir el evento analizado en handle() evita el problema por completo.

3. Normaliza los nombres de eventos en el límite. Mapea las cadenas de tipo de cada proveedor a un vocabulario interno único antes de que tu lógica de negocio las vea:

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. Ten en cuenta la ventana de frescura. Las mejores prácticas de Google te dicen rechazar payloads cuyo webhook-timestamp sea anterior a cinco minutos, para mitigar ataques de repetición. Una entrega guardada reproducida una hora después debería fallar un manejador correcto. Para webhooks estáticos y firmas estilo OpenAI, vuelve a firmar las entregas de prueba con un secreto de prueba y una marca de tiempo fresca, o haz que la tolerancia sea configurable solo en desarrollo.

5. Simula la obtención del puntero. Coloca un pequeño archivo de salida en disco y reemplaza tu Files API o lector de almacenamiento por uno local. Así, el evento de éxito se convierte en una prueba rápida y fuera de línea que no necesita credenciales en la nube.

6. Prueba los casos de fallo. Guarda fixtures para batch.failed, batch.expired y batch.cancelled también, ya que rara vez ves estos en tráfico real. Incluye un batch de OpenAI con un error_file_id no vacío. También escribe a mano una entrega duplicada con el mismo webhook-id para confirmar que tu verificación de idempotencia funciona.

7. Usa las herramientas de pruebas de los proveedores cuando existan. La página de configuración de webhooks del panel de OpenAI puede activar eventos de prueba con datos de muestra, y su referencia de API enumera un método “Test Webhook Endpoint”. Los webhooks de Gemini no describen un equivalente, por lo que tus fixtures grabados hacen ese trabajo.

8. Alinea con una sola consulta. Los reintentos son finitos: 24 horas en Gemini, hasta 72 horas en OpenAI. Si tu punto final está caído por más tiempo, el evento se pierde, y un batch puede tardar hasta 24 horas. Al iniciar, revisa tu libro de trabajos para buscar los que aún están marcados como submitted y verifica su estado con un único GET. Trata a los webhooks como la ruta rápida y al polling como una red de seguridad. Haz esto antes de que expiren los archivos de salida, que por defecto expiran 30 días en OpenAI.

Tu libro puede ser simple: ID de trabajo, proveedor, estado (submitted, succeeded, failed, cancelled, expired) y el último webhook-id procesado. Ninguno de los proveedores promete entregar en orden, así que aplica actualizaciones solo si mueven un trabajo hacia adelante, nunca hacia atrás.

Dónde ayuda un subdominio de túnel estable

Localhost no es alcanzable por Google ni OpenAI, así que necesitas una URL pública HTTPS. La guía de OpenAI reconoce esto y sugiere herramientas como ngrok, o entornos de desarrollo en la nube como Replit, GitHub Codespaces, Cloudflare Workers y v0. Lo que importa para el trabajo por batch es si esa URL permanece igual.

  • Puntos finales de OpenAI y webhooks estáticos de Gemini se registran una vez. Si la URL cambia en cada sesión, vuelves al panel o a la API para actualizarla. Un hostname fijo se puede registrar una vez y dejarlo.
  • Los webhooks dinámicos de Gemini colocan la URL dentro de cada trabajo. Puedes incrustar un hostname estable en webhook_config.uris en tu código de envío, de modo que cada trabajo que inicies ya apunte a casa.
  • Evita redirecciones en la URL registrada. OpenAI no sigue respuestas 3xx y las trata como fallos, así que registra la URL HTTPS final, incluyendo la ruta exacta.
  • La duración de la sesión debe coincidir con el horizonte del trabajo. El README de InstaTunnel anuncia una capa gratuita con sesiones de 24+ horas, subdominios personalizados como my-app.instatunnel.my, y tres túneles simultáneos. Su nivel Pro es $5/mes. Consulta la página de precios actual para conocer límites antes de depender de esto. Una sesión de túnel que dure tanto como una ventana de batch de 24 horas no garantiza que una sola sesión cubra todo el trabajo. Los reintentos del proveedor significan que una reconexión corta no debe perder el event, siempre que vuelvas a la misma dirección. npm install -g instatunnel instatunnel 3000 --subdomain my-app # https://my-app.instatunnel.my -> localhost:3000

Un túnel es suficiente si enrutas por ruta (/hooks/openai, /hooks/gemini-static, /hooks/gemini-dynamic). Un túnel separado por integración es opcional, por ejemplo si quieres logs separados. De cualquiera forma, mantén el proyecto de desarrollo de Gemini separado del de producción para que el endpoint estático solo reciba tus propios eventos.

Checklist before you ship

  • Define explícitamente los nombres de eventos: batch.completed (OpenAI) y batch.succeeded (Gemini).
  • Lee el cuerpo crudo antes de que pase cualquier middleware JSON.
  • Responde con 2xx rápidamente, luego encola el trabajo real.
  • Deduplica con webhook-id, y conserva los registros de deduplicación más allá de la ventana de reintentos (72 horas para OpenAI).
  • Verifica fallos en un batch de OpenAI con error_file_id, y busca salida parcial en batch.expired.
  • No asumas output_file_uri presente en cada evento de Gemini, y verifica lo que contienen tus entregas reales.
  • Ejecuta dos verificadores si usas ambos modelos de Gemini, y almacena en caché los JWKS.
  • No registres URLs que redirijan; OpenAI no las seguirá.
  • Añade una encuesta de reconciliación para trabajos que superen el downtime de tu endpoint.

Preguntas frecuentes

¿Los webhooks de Gemini funcionan con la Batch API?
Sí. Batch es un caso de uso principal, con eventos batch.succeeded, batch.failed, batch.cancelled y batch.expired. Webhooks también cubren Interactions y generación de video.

¿Los webhooks de Gemini están generalmente disponibles?
La publicación de lanzamiento de Google dice que están disponibles para todos los desarrolladores que usan la Gemini API, pero la documentación actualmente marca la función como vista previa. Vuelve a revisar la documentación antes de depender de detalles.

¿Cuál es la diferencia entre webhooks estáticos y dinámicos de Gemini?
Los webhooks estáticos son endpoints a nivel de proyecto creados a través de la API de WebhookService y firmados con un secreto HMAC. Los webhooks dinámicos se configuran por solicitud mediante webhook_config y se firman con un JWT que verificas contra las claves públicas de Google.

¿El webhook contiene mis batch results?
No. Gemini envía un puntero (como el output_file_uri en el ejemplo de Google), y OpenAI envía solo el ID del batch, después del cual obtienes el archivo de salida.

¿Cuánto tiempo siguen intentando los proveedores?
Google reintenta durante 24 horas con retroceso exponencial. OpenAI reintenta hasta 72 horas con retroceso exponencial.

¿Puedo probar los webhooks de OpenAI sin ejecutar un trabajo?
Sí. La página de configuración de webhooks del panel puede enviar eventos de prueba con datos de muestra.

¿OpenAI seguirá una redirección en mi URL de webhook?
No. Las respuestas 3xx se tratan como fallos, así que registra la URL final.

Conclusión

Los callbacks de IA asíncronos son fáciles de recibir y difíciles de depurar porque sus entradas son costosas de reproducir. Captura una entrega real, separa la verificación del manejo, simula la obtención de resultados y mantiene un barrido de polling para cualquier cosa que supere tu ventana de reintentos. Entonces el batch solo tiene que ejecutarse una vez, y todo lo demás es un fixture.


Fuentes

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