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

Hero

#새로운 방식: 웹훅

웹훅을 사용하면 작업 시작 단계와 결과 수신 단계가 완전히 분리됩니다. 요청을 보내면서 콜백 URL만 제공하면 됩니다:

// 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.
}

그리고 서버에서는 결과가 준비되었을 때 이를 수신할 전용 엔드포인트를 열어둡니다:

// 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");
});