Reduce Friction and Latency for Long-Running Jobs with Webhooks in Gemini API

Hero

#O jeito novo: Webhooks

Com webhooks, a etapa de iniciação é totalmente desacoplada da etapa de recuperação de dados. Você simplesmente dispara a requisição e informa a sua URL de callback:

// Modern Webhook Approach: Initiating the job
async function initiateVideoProcessing(fileId) {
  await fetch('https://api.gemini.com/v1/jobs/analyze', {
    method: 'POST',
    body: JSON.stringify({ 
      fileId: fileId, 
      prompt: "Extract key moments.",
      webhook_url: "https://api.ichiban-tools.com/webhooks/gemini/video-complete"
    })
  });
  // Return immediately; the user can continue navigating the app.
}

O seu servidor, então, expõe um endpoint dedicado para receber o resultado assim que ele estiver pronto:

// Express.js Webhook Receiver
app.post('/webhooks/gemini/video-complete', express.json(), (req, res) => {
  // 1. Verify the signature to ensure the request actually came from Google
  if (!verifyGeminiSignature(req)) {
    return res.status(401).send("Unauthorized");
  }

  const { jobId, status, result, error } = req.body;
  
  if (status === "COMPLETED") {
    // 2. Process the results asynchronously (e.g., save to DB, notify user via WebSocket)
    database.saveAnalysis(jobId, result);
    notifier.sendWebSocketMessage(jobId, "Analysis Complete!");
  } else if (status === "FAILED") {
    errorHandler.logAndAlert(jobId, error);
  }

  // 3. Acknowledge receipt quickly to prevent webhook retries
  res.status(200).send("OK");
});