Gemini API ahora tiene webhooks: el fin del polling en pipelines Veo y batch

El patrón while not operation.done: sleep(5) es código que todo equipo que trabaja con generación de video o batch jobs conoce de memoria. Funciona, pero es un antipatrón: bloquea hilos, desperdicia llamadas a la API en verificaciones de estado e introduce latencia artificial proporcional al intervalo de polling. Con el anuncio de hoy de Google AI Studio, ese código puede — y debe — ser retirado.

Qué se anunció

Google lanzó soporte de webhooks en la Gemini API, cubriendo tres clases de eventos:

• Generación de video completada — video.generated con Veo (incluyendo veo-3.1-generate-preview)
• Batch job finalizado — notificación al terminar jobs de procesamiento por lotes
• Workflow agéntico necesita atención — disparador para human-in-the-loop en pipelines de agentes

La especificación técnica es Standard Webhooks (standardwebhooks.com): solicitudes HTTP POST con payload firmado por HMAC, cabeceras webhook-id + webhook-timestamp + webhook-signature, y semántica de entrega at-least-once con retry exponencial.

Dos modos de registro

La API soporta dos modos de configuración:

Estático (nivel de proyecto): configurado vía Google Cloud Console o API de administración. Todas las operaciones del proyecto envían notificaciones al endpoint registrado. Ideal para pipelines de producción con receptor centralizado.

Dinámico (por solicitud): pasado inline en la llamada a la API. Cada job puede indicar su propio endpoint — útil en arquitecturas multi-tenant donde cada cliente tiene su propio receiver, o en flujos de prueba.

SDK Python: cómo queda el código

Antes (polling):

import time
from google import genai

client = genai.Client()
operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="time-lapse of a server room at night",
)

# Loop de polling — bloquea el hilo, desperdicia llamadas
while not operation.done:
    time.sleep(10)
    operation = client.operations.get(operation)

video = operation.result.generated_videos[0]

Después (webhook):

from google import genai
from google.genai import types

client = genai.Client()

# Registro dinámico: el job notifica a su receptor al completarse
operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="time-lapse of a server room at night",
    config=types.GenerateVideoConfig(
        webhook=types.WebhookConfig(
            uri="https://tu-api.com/webhooks/gemini",
            subscribed_events=["video.generated"],
        )
    ),
)

# Retorna inmediatamente — sin bloqueo
print(f"Job iniciado: {operation.name}")

El receptor recibe un HTTP POST con payload firmado:

# Receptor FastAPI (ejemplo mínimo)
from fastapi import FastAPI, Request, Header
import hmac, hashlib, base64

app = FastAPI()

WEBHOOK_SECRET = "tu-secreto-aquí"

@app.post("/webhooks/gemini")
async def handle_gemini_event(
    request: Request,
    webhook_signature: str = Header(None),
):
    body = await request.body()

    # Verificación de firma (Standard Webhooks)
    expected = base64.b64encode(
        hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).digest()
    ).decode()

    if not hmac.compare_digest(expected, webhook_signature.split(",")[-1]):
        return {"error": "invalid signature"}, 401

    payload = await request.json()
    event_type = payload["type"]  # "video.generated"

    if event_type == "video.generated":
        video_uri = payload["data"]["uri"]
        # disparar downstream: guardar en GCS, notificar usuario, etc.

    return {"ok": True}

Por qué esto cambia la arquitectura

El polling era un hack de conveniencia que funcionaba para prototipos pero no escala. Tres problemas reales que crea en producción:

1. Hilos bloqueados. En Python síncrono, cada job en curso retiene un hilo esperando. Con 50 generaciones simultáneas, necesitas 50 workers solo para esperar.

2. Latencia artificial. Un intervalo de 10 segundos significa que entregas el video, en promedio, 5 segundos más tarde de lo necesario. Con webhooks, la notificación llega en milisegundos tras la finalización.

3. Fragilidad ante reinicios. Si el proceso que ejecuta el loop se cae, pierdes el estado de la operación. Con webhooks, el receptor es stateless — Google reenvía si no recibe un 2xx.

Un webhook no es solo una notificación más rápida — es un contrato de inversión de control. El modelo te llama; tú no necesitas seguir llamando al modelo.

Standard Webhooks: el detalle que importa para equipos de plataforma

Que la Gemini API adopte la especificación Standard Webhooks no es un detalle menor. Significa que el mismo código de validación de firma que ya usas para eventos de Stripe o GitHub funciona aquí — solo cambia el secreto y el nombre del campo de cabecera.

Para equipos que ya tienen infraestructura de ingestión de eventos (un receptor FastAPI/Express, una cola SQS o Pub/Sub al frente), integrar Gemini no requiere nuevo código de verificación. Solo registra el endpoint y agrega handlers para los tipos de eventos de Gemini.

Implicaciones para pipelines agénticos

Además de Veo y batch jobs, el anuncio cubre un tercer evento: agent.needs_attention — disparado cuando un workflow agéntico llega a un punto de decisión que requiere intervención humana.

Este es el primitivo que faltaba para human-in-the-loop en producción. Antes, tenías que implementar una cola de aprobación desde cero (polling de base de datos, WebSocket, o long-poll HTTP). Con el evento nativo, el agente te empuja la notificación — y el revisor humano puede responder vía API antes de que el agente continúe.

Para equipos que construyen pipelines de aprobación multi-step (KYC, contratos, análisis de riesgo), esto reduce significativamente la complejidad de la capa de orquestación.

Leer más