Webhooks

Los webhooks permiten que la API de Gemini envíe notificaciones en tiempo real a tu servidor cuando se completan las operaciones asíncronas o de larga duración (LRO). Esto reemplaza la necesidad de sondear la API para obtener actualizaciones de estado, lo que reduce la latencia y la sobrecarga.

Los webhooks están disponibles para operaciones como trabajos por lotes, interacciones y generación de video.

Cómo funciona

En lugar de sondear GET /operations de forma repetida para verificar si se completó un trabajo, puedes configurar los webhooks de la API de Gemini para que envíen una solicitud HTTP POST a la URL del objeto de escucha inmediatamente después de que se active un evento.

La API de Gemini admite dos formas de configurar webhooks:

• Webhooks estáticos: Son extremos a nivel del proyecto configurados con la API de WebhookService de Gemini. Son adecuados para integraciones globales (p. ej., notificar a Slack, sincronizar una base de datos, etcétera).
• Webhooks dinámicos: Son anulaciones a nivel de la solicitud que pasan una URL de webhook en la carga útil de configuración de una llamada de trabajos específica. Son ideales para enrutar trabajos específicos a extremos dedicados.

Webhooks estáticos

Los webhooks estáticos se registran para todo un proyecto y se activan para cualquier evento coincidente.

Crea un webhook

Puedes crear extremos con el SDK o la API de REST.

IMPORTANTE: Cuando se crea un webhook, la API muestra un secreto de firma solo una vez. Debes almacenarlo de forma segura (p.ej., en tus variables de entorno) para verificar las firmas más adelante. Si pierdes el secreto de firma, deberás rotarlo.

from google import genai

client = genai.Client()

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

# Store webhook.new_signing_secret securely
webhook_secret = webhook.new_signing_secret
print(f"Created webhook: {webhook.name}, {webhook.id}")

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function createWebhook() {
  const webhook = await client.webhooks.create({
    name: "MyBatchWebhook",
    subscribed_events: ["batch.succeeded", "batch.failed"],
    uri: "https://my-api.com/gemini-callback",
  });

  // Store webhook.signingSecret securely
  const webhookSecret = webhook.new_signing_secret;
  console.log(`Created webhook: ${webhook.name}, ${webhook.id}`);
}

createWebhook();

curl -X POST \
  "https://generativelanguage.googleapis.com/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "name": "MyBatchWebhook",
    "uri": "https://my-api.com/gemini-callback",
    "subscribed_events": ["batch.succeeded", "batch.failed"]
  }'

Para obtener detalles sobre cómo configurar tu servidor para recibir datos, consulta la