Si alguna vez ha creado un canal de producción de IA que ejecuta trabajos prolongados (procesando miles de solicitudes durante la noche, iniciando un agente de investigación profunda o generando un video largo), es casi seguro que se ha ocupado del problema de las encuestas. Su código se encuentra en un bucle y activa solicitudes GET cada pocos segundos que preguntan: “¿Ya terminó el trabajo?” Es un desperdicio, agrega latencia y, a escala, se convierte en un dolor de cabeza en términos de confiabilidad. Google acaba de enviar la solución.
Google introdujo Webhooks basados en eventos para la API Gemini, un sistema de notificación push que elimina la necesidad de realizar encuestas ineficientes. La función ya está disponible para todos los desarrolladores que utilizan la API de Gemini y apunta a un punto central en los flujos de trabajo de inteligencia artificial de alto volumen y agentes.
Por qué las encuestas fracasan a gran escala
Para comprender el problema, es útil saber qué es la operación de larga duración (LRO). Los webhooks permiten que la API de Gemini envíe notificaciones en tiempo real a su servidor cuando se completan operaciones asíncronas o de larga duración, reemplazando la necesidad de sondear la API para obtener actualizaciones de estado y reduciendo la latencia y la sobrecarga.
Antes de los webhooks, la única opción era el sondeo continuo: llamar repetidamente a GET /operaciones para comprobar si un trabajo había finalizado. A medida que Gemini avanza hacia flujos de trabajo agentes y procesamiento de gran volumen (como investigación profunda, generación de videos largos o procesamiento de miles de solicitudes a través de Batch API), las operaciones pueden llevar minutos o incluso horas. El sondeo durante horas es costoso tanto en términos de computación como de cuota de API, e introduce retrasos innecesarios entre el momento en que se completa un trabajo y el momento en que la aplicación se entera de ello.
La solución es conceptualmente simple: en lugar de que el código pregunte “¿ya terminaste?” repetidamente, la API de Gemini llama a su servidor en el momento en que finaliza una tarea, enviando una carga útil HTTP POST en tiempo real a su punto final en el instante en que se completa una tarea.
Dos modos de configuración: estático y dinámico
La API de Gemini admite dos formas de configurar webhooks. Los webhooks estáticos son puntos finales a nivel de proyecto configurados con la API WebhookService y son adecuados para integraciones globales como notificar a Slack o sincronizar una base de datos: se registran una vez por proyecto y activan cualquier evento coincidente. Los webhooks dinámicos son anulaciones a nivel de solicitud que pasan una URL de webhook en la carga útil webhook_config de una llamada de trabajo específica, lo que los hace ideales para enrutar trabajos específicos a puntos finales dedicados, por ejemplo, en colas de orquestación de agentes.
Puede pensar en los webhooks estáticos como una instrucción permanente para su cartero: “Entregue siempre los paquetes en la recepción”. Los webhooks dinámicos son más como decir: “Para este envío, envíelo a mi dirección particular”. Una característica adicional de los webhooks dinámicos es el campo user_metadata, que le permite adjuntar metadatos de valores-clave arbitrarios a un trabajo en el momento del envío, por ejemplo, {“job_group”: “nightly-eval”, “priority”: “high”}. Estos metadatos viajan con la notificación del trabajo y son particularmente útiles cuando necesita distribuir diferentes tipos de trabajos a diferentes procesadores posteriores sin crear una capa de seguimiento separada.
Arquitectura de seguridad: Webhooks estándar, HMAC y JWKS
La seguridad es donde esta implementación se vuelve técnicamente interesante. La implementación de Google se adhiere estrictamente a la especificación de Webhooks estándar. Cada solicitud se firma utilizando los encabezados webhook-signature, webhook-id y webhook-timestamp, lo que garantiza la idempotencia y evita ataques de repetición.
Para los webhooks estáticos, la firma se realiza con HMAC (Código de autenticación de mensajes basado en hash) utilizando un secreto compartido simétrico, que se proporciona una vez en el momento de la creación y debe almacenarse de forma segura en sus variables de entorno; la API devuelve este secreto de firma solo una vez y no se puede recuperar nuevamente. Si lo pierdes, tendrás que rotarlo. El punto final de rotación admite un parámetro revocation_behavior, específicamente REVOKE_PREVIOUS_SECRETS_AFTER_H24, que mantiene el antiguo secreto válido durante un período de gracia de 24 horas para que pueda realizar una transición segura de los sistemas de producción, o una opción de revocación inmediata para respuesta a incidentes.
Para los webhooks dinámicos, Google utiliza firmas JWKS (JSON Web Key Set) de clave pública asimétrica en lugar de secretos simétricos. Las solicitudes de webhook dinámico emiten una firma de token web JSON (JWT) y su oyente debe extraerla y verificarla mediante los puntos finales de certificados públicos de Google en https://generativelanguage.googleapis.com/.well-known/jwks.json. Para esta verificación se utiliza el algoritmo RS256.
Esto significa que su servidor nunca confía ciegamente en las solicitudes entrantes: cada acceso al webhook se puede verificar criptográficamente antes de actuar en consecuencia. El encabezado webhook-timestamp es particularmente importante: las mejores prácticas exigen validar siempre esta marca de tiempo y rechazar cargas útiles de más de cinco minutos para mitigar los ataques de repetición.
Cargas útiles delgadas y el catálogo de eventos
Una decisión arquitectónica que vale la pena destacar es el modelo de carga útil delgada. Para evitar la congestión del ancho de banda, los webhooks de Gemini entregan una instantánea que contiene detalles del estado y punteros a los resultados, en lugar del archivo de salida sin formato en sí. Los campos exactos en esa instantánea dependen del tipo de evento.
Para trabajos por lotes, una notificación completa lleva la identificación del trabajo y un uri_archivo_salida que apunta a sus resultados; por ejemplo, una ruta de Cloud Storage como gs://my-bucket/results.jsonl. Para la generación de videos, el evento video.generated entrega un conjunto diferente de campos: file_id y video_uri. Su controlador del lado del servidor debe bifurcarse según el tipo de evento antes de leer los campos de datos de carga útil.
El catálogo completo de eventos cubre tres categorías: trabajos por lotes (batch.succeeded, lote.cancelled, lote.expired, lote.failed), operaciones API de Interacciones (interaction.requires_action, interacción.completada, interacción.failed, interacción.cancelled) y generación de video (video.generated). Para los desarrolladores que escriben código: los ejemplos de código oficial en la documentación de Google se suscriben y manejan lote.completado en lugar de lote.succeeded; ambos aparecen en la documentación, así que haga coincidir lo que utilice su implementación.
La API de Interacciones, para los lectores que no estén familiarizados con ella, es la API de Gemini para conversaciones asíncronas de agentes de varios turnos. El evento interactuación.requires_action es particularmente útil: se activa cuando hay una llamada de función pendiente y su aplicación debe intervenir y realizar una acción antes de que el agente pueda continuar.
Garantías de entrega y mejores prácticas
Google garantiza la entrega “al menos una vez” con reintentos automáticos durante hasta 24 horas mediante un retroceso exponencial. La garantía “al menos una vez” significa que su punto final ocasionalmente podría recibir el mismo evento más de una vez en condiciones de alta congestión. Se debe utilizar el encabezado webhook-id consistente para deduplicarlos. Su servidor también debe responder con un código de estado 2xx inmediatamente después de la detección de una firma válida y poner en cola cualquier análisis más intenso internamente; los tiempos de espera prolongados del oyente desencadenan el ciclo de reintento, que es lo opuesto a lo que usted desea.
Conclusiones clave
No más bucles de sondeo: la API de Gemini ahora envía un POST HTTP firmado a su servidor en el instante en que se completa un trabajo de larga duración (API por lotes, investigación profunda, generación de video), eliminando la necesidad de llamar repetidamente a GET /operaciones. Dos modos de webhook para diferentes arquitecturas: los webhooks estáticos manejan integraciones globales a nivel de proyecto aseguradas a través de HMAC; Los webhooks dinámicos se vinculan a solicitudes de trabajo individuales a través de firmas JWKS y admiten metadatos de usuario para una lógica de enrutamiento personalizada en canales de orquestación de agentes. La seguridad está integrada, no incorporada: cada notificación está firmada criptográficamente según la especificación de Webhooks estándar mediante encabezados webhook-signature, webhook-id y webhook-timestamp. Rechace cargas útiles de más de 5 minutos para bloquear ataques de repetición y utilice webhook-id para deduplicar entregas al menos una vez. Cargas útiles delgadas, no resultados sin procesar: las notificaciones de Webhook contienen indicadores de estado, no datos de salida. Los eventos por lotes devuelven output_file_uri; los eventos de video devuelven file_id y video_uri. Responda siempre 2xx inmediatamente y procese de forma asincrónica: las respuestas lentas desencadenan reintentos de retroceso exponencial durante hasta 24 horas.
Consulta los detalles técnicos aquí. Además, no dude en seguirnos en Twitter y no olvide unirse a nuestro SubReddit de más de 130.000 ML y suscribirse a nuestro boletín. ¡Esperar! estas en telegrama? Ahora también puedes unirte a nosotros en Telegram.
¿Necesita asociarse con nosotros para promocionar su repositorio de GitHub O su página principal de Hugging O su lanzamiento de producto O seminario web, etc.? Conéctate con nosotros
Michal Sutter es un profesional de la ciencia de datos con una Maestría en Ciencias de Datos de la Universidad de Padua. Con una base sólida en análisis estadístico, aprendizaje automático e ingeniería de datos, Michal se destaca en transformar conjuntos de datos complejos en conocimientos prácticos.