I webhook consentono all'API Gemini di inviare notifiche in tempo reale al tuo server al termine delle operazioni asincrone o a lunga esecuzione (LRO). In questo modo, non è più necessario eseguire il polling dell'API per gli aggiornamenti di stato, riducendo la latenza e il sovraccarico.
I webhook sono disponibili per operazioni come job batch, interazioni e generazione di video.
Come funziona
Anziché eseguire ripetutamente il polling di GET /operations per verificare se un job è terminato, puoi configurare i webhook dell'API Gemini in modo che inviino una richiesta HTTP POST all'URL del listener immediatamente dopo l'attivazione di un evento.
L'API Gemini supporta due modi per configurare i webhook:
- Webhook statici: endpoint a livello di progetto configurati con l'API Gemini WebhookService. Ideali per le integrazioni globali (ad es. invio di notifiche a Slack, sincronizzazione di un database e così via).
- Webhook dinamici: override a livello di richiesta che passano un URL webhook nel payload di configurazione di una chiamata di job specifica. Ideali per il routing di job specifici a endpoint dedicati.
Webhook statici
I webhook statici vengono registrati per un intero progetto e vengono attivati per qualsiasi evento corrispondente.
Crea un webhook
Puoi creare endpoint utilizzando l'SDK o l'API REST.
IMPORTANTE: quando crei un webhook, l'API restituisce un secret di firma una sola volta. Devi archiviarlo in modo sicuro (ad es. nelle variabili di ambiente) per verificare le firme in un secondo momento. Se perdi il secret di firma, dovrai ruotarlo.