Google adiciona webhooks orientados a eventos à API Gemini, eliminando a premência de pesquisas em trabalhos de IA de longa duração | NeuralNet IA

🇧🇷 O Que Isso Significa para o Brasil?

Com o propagação do ecossistema de IA no país e discussões sobre regulação (PL 2338/2023), avanços em perceptibilidade sintético, machine learning e automação impactam diretamente profissionais, startups e empresas brasileiras. Fique prudente a:

• 🎓 Capacitação profissional: Demanda por habilidades em IA cresce 3x ao ano no mercado brasílico
• ⚖️ Marco Regulatório: Proposta de lei sobre IA pode afetar desenvolvimento e uso de ferramentas
• 🏢 Adoção empresarial: Setores uma vez que saúde, jurídico e financeiro lideram implementação de IA no Brasil

Se você já construiu um pipeline de IA de produção que executa trabalhos longos – processando milhares de prompts durante a noite, iniciando um agente de pesquisa profunda ou gerando um vídeo longo – é quase notório que você já lidou com o problema da pesquisa. Seu código fica em loop, disparando GET solicita a cada poucos segundos perguntando: “O trabalho já foi concluído?” É um desperdício, aumenta a latência e, em graduação, torna-se uma dor de cabeça em termos de confiabilidade. O Google acabou de enviar a correção.

Google apresentou Webhooks orientados a eventos para a API Gemini — um sistema de notificação fundamentado em push que elimina a premência de pesquisas ineficientes. O recurso já está disponível para todos os desenvolvedores que usam a API Gemini e tem uma vez que níveo um ponto problemático médio em fluxos de trabalho de IA de cima volume e agentes.

Por que as pesquisas se dividem em grande graduação

Para entender o problema, é útil saber o que é Operação de Longa Duração (LRO). Os webhooks permitem que a API Gemini envie notificações em tempo real para o seu servidor quando operações assíncronas ou de longa duração são concluídas, substituindo a premência de pesquisar a API para atualizações de status e reduzindo a latência e a sobrecarga.

Antes dos webhooks, a única opção era a pesquisa contínua – vincular repetidamente GET /operations para verificar se um trabalho foi concluído. À medida que o Gemini muda para fluxos de trabalho de agentes e processamento de cima volume — uma vez que pesquisa profunda, geração de vídeos longos ou processamento de milhares de prompts por meio da API Batch — as operações podem levar minutos ou até horas. A pesquisa por horas é faceta tanto na prestação de computação quanto na prestação de API e introduz atrasos desnecessários entre a desenlace de um trabalho e o momento em que seu aplicativo toma conhecimento dele.

A correção é conceitualmente simples: em vez de seu código perguntar “você terminou?” repetidamente, a API Gemini labareda seu servidor no momento em que uma tarefa é concluída, enviando uma trouxa HTTP POST em tempo real para seu endpoint no momento em que uma tarefa é concluída.

Dois modos de feitio: estático e dinâmico

A API Gemini oferece suporte a duas maneiras de configurar webhooks. Webhooks estáticos são endpoints em nível de projeto configurados com a API WebhookService e são adequados para integrações globais, uma vez que notificação do Slack ou sincronização de um banco de dados – eles são registrados uma vez por projeto e acionados para qualquer evento correspondente. Webhooks dinâmicos são substituições em nível de solicitação que passam um URL de webhook no webhook_config trouxa útil de uma chamada de trabalho específica, tornando-os ideais para rotear trabalhos específicos para terminais dedicados, por exemplo, em filas de orquestração de agentes.

Você pode pensar em webhooks estáticos uma vez que uma instrução permanente para seu carteiro: “Sempre entregue os pacotes na recepção”. Webhooks dinâmicos são mais uma vez que expressar: “Para esta remessa, envie-a para meu endereço residencial”. Um recurso suplementar dos webhooks dinâmicos é o user_metadata campo, que permite apender metadados de valor-chave arbitrários a um trabalho no momento do envio — por exemplo, {"job_group": "nightly-eval", "priority": "high"}. Esses metadados acompanham a notificação de trabalho e são particularmente úteis quando você precisa partilhar diferentes tipos de trabalho para diferentes processadores downstream sem fabricar uma categoria de rastreamento separada.

Arquitetura de segurança: Webhooks padrão, HMAC e JWKS

A segurança é onde esta implementação se torna tecnicamente interessante. A implementação do Google segue estritamente a especificação Standard Webhooks. Cada solicitação é assinada usando webhook-signature, webhook-ide webhook-timestamp cabeçalhos, garantindo idempotência e evitando ataques de repetição.

Para webhooks estáticos, a assinatura é feita com HMAC (Hash-based Message Authentication Code) usando um sigilo compartilhado simétrico, que é fornecido uma vez no momento da geração e deve ser armazenado com segurança em suas variáveis ​​de envolvente — a API retorna esse sigilo de assinatura exclusivamente uma vez e não pode ser renovado novamente. Se você perdê-lo, terá que girá-lo. O ponto final de rotação suporta um revocation_behavior parâmetro – especificamente REVOKE_PREVIOUS_SECRETS_AFTER_H24que mantém o macróbio sigilo válido por um período de carência de 24 horas para que você possa fazer a transição segura dos sistemas de produção ou uma opção de revogação imediata para resposta a incidentes.

Para webhooks dinâmicos, o Google usa assinaturas JWKS (JSON Web Key Set) de chave pública assimétrica em vez de segredos simétricos. As solicitações dinâmicas de webhook emitem uma assinatura JSON Web Token (JWT), e seu ouvinte deve extraí-la e verificá-la usando os pontos de extremidade do certificado público do Google em https://generativelanguage.googleapis.com/.well-known/jwks.json. O algoritmo RS256 é usado para esta verificação.

Isso significa que seu servidor nunca confia cegamente nas solicitações recebidas – cada acerto de webhook pode ser verificado criptograficamente antes de você agir de consonância. O webhook-timestamp O cabeçalho é particularmente importante: as práticas recomendadas exigem sempre a validação desse timbre de data/hora e a repudiação de cargas com mais de cinco minutos para mitigar ataques de repetição.

Cargas úteis finas e o catálogo de eventos

Uma decisão arquitetônica digna de nota é o padrão de trouxa útil reduzida. Para evitar o congestionamento da largura de margem, os webhooks Gemini fornecem um momentâneo contendo detalhes de status e ponteiros para resultados, em vez do próprio registro de saída bruto. Os campos exatos nesse momentâneo dependem do tipo de evento.

Para trabalhos em lote, uma notificação concluída carrega o trabalho id e um output_file_uri apontando para seus resultados, por exemplo, um caminho do Cloud Storage uma vez que gs://my-bucket/results.jsonl. Para geração de vídeo, o video.generated event fornece um conjunto dissemelhante de campos: file_id e video_uri. Seu manipulador do lado do servidor precisa ramificar o tipo de evento antes de ler os campos de dados de trouxa útil.

O catálogo completo de eventos abrange três categorias: trabalhos em lote (batch.succeeded, batch.cancelled, batch.expired, batch.failed), operações da API de interações (interaction.requires_action, interaction.completed, interaction.failed, interaction.cancelled) e geração de vídeo (video.generated). Para desenvolvedores que escrevem código: os exemplos de código oficiais na documentação do Google assinam e tratam batch.completed em vez de batch.succeeded – ambos aparecem na documentação, portanto, corresponda ao que sua implementação usa.

A API de interações, para leitores não familiarizados com ela, é a API do Gemini para conversas assíncronas com agentes multiturno. O interaction.requires_action O evento é particularmente útil — ele é acionado quando uma chamada de função está pendurado e seu aplicativo precisa intervir e executar uma ação antes que o agente possa continuar.

Garantias de entrega e melhores práticas

O Google garante entrega “pelo menos uma vez” com novas tentativas automáticas por até 24 horas usando espera exponencial. A garantia “pelo menos uma vez” significa que seu endpoint pode ocasionalmente receber o mesmo evento mais de uma vez em condições de cima congestionamento. O consistente webhook-id header deve ser usado para desduplicá-los. Seu servidor também deve responder com um 2xx código de status imediatamente em seguida a detecção de assinatura válida e enfileirar qualquer estudo mais pesada internamente – tempos de espera prolongados do ouvinte acionam o ciclo de novidade tentativa, que é o oposto do que você deseja.

Principais conclusões

• Não há mais ciclos de votação — A API Gemini agora envia um HTTP POST assinado para o seu servidor no momento em que um trabalho de longa duração (API em lote, pesquisa profunda, geração de vídeo) é concluído, eliminando a premência de invocar repetidamente GET /operations.
• Dois modos de webhook para diferentes arquiteturas — Webhooks estáticos lidam com integrações globais em nível de projeto protegidas via HMAC; Webhooks dinâmicos vinculam-se a solicitações de trabalho individuais por meio de assinaturas e suporte JWKS user_metadata para lógica de roteamento personalizada em pipelines de orquestração de agentes.
• A segurança está integrada, não aparafusada — Cada notificação é assinada criptograficamente de consonância com a especificação Standard Webhooks usando webhook-signature, webhook-ide webhook-timestamp cabeçalhos. Rejeite cargas com mais de 5 minutos para bloquear ataques de repetição e use webhook-id para desduplicar entregas pelo menos uma vez.
• Cargas úteis finas, não resultados brutos — As notificações de webhook carregam ponteiros de status, não dados de saída. Retorno de eventos em lote output_file_uri; retorno de eventos de vídeo file_id e video_uri. Sempre responda 2xx imediatamente e processe de forma assíncrona – respostas lentas acionam novas tentativas de espera exponencial por até 24 horas.

---

📚 Leia Também no NeuralNet:

• 👉 Guia de Inteligência Artificial para Iniciantes
• 👉 Melhores Ferramentas de IA para Aumentar sua Produtividade
• 👉 Ética e Regulação de IA no Brasil: O Que Você Precisa Saber

⚠️ Aviso Importante: Oriente teor é exclusivamente para fins educacionais e informativos. Não constitui aconselhamento técnico, jurídico ou profissional. Tecnologias de IA evoluem rapidamente e podem apresentar limitações, vieses ou riscos. Sempre valide informações em fontes oficiais e use ferramentas de IA com responsabilidade e sátira.