ওয়েবহুক

ওয়েবহুকের মাধ্যমে, অ্যাসিঙ্ক্রোনাস বা দীর্ঘ-চলমান অপারেশন (LRO) সম্পন্ন হলে জেমিনি এপিআই আপনার সার্ভারে রিয়েল-টাইম নোটিফিকেশন পাঠাতে পারে। এর ফলে স্ট্যাটাস আপডেটের জন্য এপিআই পোল করার প্রয়োজন হয় না, যা ল্যাটেন্সি এবং ওভারহেড কমিয়ে আনে।

ব্যাচ জব, ইন্টারঅ্যাকশন এবং ভিডিও তৈরির মতো অপারেশনের জন্য ওয়েবহুক উপলব্ধ রয়েছে।

এটি কীভাবে কাজ করে

কোনো কাজ শেষ হয়েছে কিনা তা পরীক্ষা করার জন্য বারবার GET /operations পোল করার পরিবর্তে, আপনি কোনো ইভেন্ট ট্রিগার হওয়ার সাথে সাথেই আপনার লিসেনার URL-এ একটি HTTP POST অনুরোধ পাঠানোর জন্য Gemini API Webhooks কনফিগার করতে পারেন।

জেমিনি এপিআই ওয়েবহুক কনফিগার করার দুটি উপায় সমর্থন করে:

  • স্ট্যাটিক ওয়েবহুক : জেমিনি ওয়েবহুকসার্ভিস এপিআই (Gemini WebhookService API) দিয়ে কনফিগার করা প্রোজেক্ট-স্তরের এন্ডপয়েন্ট। গ্লোবাল ইন্টিগ্রেশনের জন্য উপযোগী (যেমন, স্ল্যাক-এ নোটিফাই করা, ডাটাবেস সিঙ্ক করা, ইত্যাদি)।
  • ডাইনামিক ওয়েবহুক : এটি কোনো নির্দিষ্ট জব কলের কনফিগারেশন পেলোডে ওয়েবহুক ইউআরএল পাস করার পরিবর্তে রিকোয়েস্ট-লেভেলে ওভাররাইড করে। নির্দিষ্ট জবকে ডেডিকেটেড এন্ডপয়েন্টে রাউট করার জন্য এটি আদর্শ।

স্ট্যাটিক ওয়েবহুক

পুরো প্রোজেক্টের জন্য স্ট্যাটিক ওয়েবহুকগুলো রেজিস্টার করা হয় এবং যেকোনো ম্যাচিং ইভেন্টের জন্য সেগুলো ট্রিগার হয়।

একটি ওয়েবহুক তৈরি করুন

আপনি SDK অথবা REST API ব্যবহার করে এন্ডপয়েন্ট তৈরি করতে পারেন।

গুরুত্বপূর্ণ : একটি ওয়েবহুক তৈরি করার সময়, এপিআই শুধুমাত্র একবার একটি সাইনিং সিক্রেট ফেরত দেয়। পরবর্তীতে সিগনেচার যাচাই করার জন্য আপনাকে অবশ্যই এটি নিরাপদে সংরক্ষণ করতে হবে (যেমন আপনার এনভায়রনমেন্ট ভেরিয়েবলে)। আপনি যদি সাইনিং সিক্রেটটি হারিয়ে ফেলেন, তবে আপনাকে এটি রোটেট করতে হবে।

পাইথন

from google import genai

client = genai.Client()

webhook = client.webhooks.create(
    name="MyBatchWebhook",
    subscribed_events=["batch.completed", "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.completed", "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: $GOOGLE_API_KEY" \
  -d '{
    "name": "MyBatchWebhook",
    "uri": "https://my-api.com/gemini-callback",
    "subscribed_events": ["batch.completed", "batch.failed"]
  }'

ডেটা গ্রহণের জন্য আপনার সার্ভার সেট আপ করার বিস্তারিত তথ্যের জন্য, “ওয়েবহুক অনুরোধ পরিচালনা” বিভাগটি দেখুন।

একটি ওয়েবহুক পান

কোনো নির্দিষ্ট ওয়েবহুকের রিসোর্স নাম ব্যবহার করে তার বিস্তারিত তথ্য পুনরুদ্ধার করুন।

পাইথন

from google import genai

client = genai.Client()

webhook = client.webhooks.get(id="<your_webhook_id>")

print(f"Webhook: {webhook.name}")
print(f"URI: {webhook.uri}")
print(f"Events: {webhook.subscribed_events}")

জাভাস্ক্রিপ্ট

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

const client = new GoogleGenAI(); // Assumes process.env.GEMINI_API_KEY is set

async function getWebhook() {
  const webhook = await client.webhooks.get("<your_webhook_id>");

  console.log(`Webhook: ${webhook.name}`);
  console.log(`URI: ${webhook.uri}`);
  console.log(`Events: ${webhook.subscribed_events}`);
}

getWebhook();

বিশ্রাম

curl -X GET \
  "https://generativelanguage.googleapis.com/v1/webhooks/<your_webhook_id>" \
  -H "x-goog-api-key: $GOOGLE_API_KEY"

ওয়েবহুকগুলির তালিকা

বর্তমান প্রজেক্টের জন্য কনফিগার করা সমস্ত ওয়েবহুকের তালিকা দেখুন, সাথে ঐচ্ছিক পেজিনেশন সুবিধাও রয়েছে।

পাইথন

from google import genai

client = genai.Client()

webhooks = client.webhooks.list()

for wh in webhooks:
    print(f"{wh.id}: {wh.name} -> {wh.uri}")

জাভাস্ক্রিপ্ট

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

const client = new GoogleGenAI();

async function listWebhooks() {
  const webhooks = await client.webhooks.list();

  for (const wh of webhooks) {
    console.log(`${wh.id}: ${wh.name} -> ${wh.uri}`);
  }
}

listWebhooks();

বিশ্রাম

curl -X GET \
  "https://generativelanguage.googleapis.com/v1/webhooks" \
  -H "x-goog-api-key: $GOOGLE_API_KEY"

একটি ওয়েবহুক আপডেট করুন

বিদ্যমান ওয়েবহুকের প্রোপার্টি, যেমন ডিসপ্লে নেম, টার্গেট ইউআরআই, বা সাবস্ক্রাইব করা ইভেন্টগুলো আপডেট করুন।

পাইথন

from google import genai

client = genai.Client()

updated_webhook = client.webhooks.update(
    id="<your_webhook_id>",
    subscribed_events=["batch.completed", "batch.failed", "batch.cancelled"],
)

print(f"Updated webhook: {updated_webhook.name}")

জাভাস্ক্রিপ্ট

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

const client = new GoogleGenAI();

async function updateWebhook() {
  const updatedWebhook = await client.webhooks.update(
    "<your_webhook_id>",
    {
      subscribed_events: ["batch.completed", "batch.failed", "batch.cancelled"],
    }
  );

  console.log(`Updated webhook: ${updatedWebhook.name}`);
}

updateWebhook();

বিশ্রাম

curl -X PATCH \
  "https://generativelanguage.googleapis.com/v1/webhooks/<your_webhook_id>" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GOOGLE_API_KEY" \
  -d '{
    "subscribed_events": ["batch.completed", "batch.failed", "batch.cancelled"]
  }'

একটি ওয়েবহুক মুছে ফেলুন

প্রজেক্ট থেকে একটি ওয়েবহুক এন্ডপয়েন্ট মুছে ফেলুন। এর ফলে ভবিষ্যতে ওই এন্ডপয়েন্টে ইভেন্ট ডেলিভারি বন্ধ হয়ে যাবে।

পাইথন

from google import genai

client = genai.Client()

client.webhooks.delete(id="<your_webhook_id>")

print("Webhook deleted.")

জাভাস্ক্রিপ্ট

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

const client = new GoogleGenAI();

async function deleteWebhook() {
  await client.webhooks.delete("<your_webhook_id>");

  console.log("Webhook deleted.");
}

deleteWebhook();

বিশ্রাম

curl -X DELETE \
  "https://generativelanguage.googleapis.com/v1/webhooks/<your_webhook_id>" \
  -H "x-goog-api-key: $GOOGLE_API_KEY"

একটি স্বাক্ষর গোপনীয়তা ঘোরান

একটি ওয়েবহুকের জন্য সাইনিং সিক্রেট পরিবর্তন করুন। পূর্বে সক্রিয় থাকা সিক্রেটগুলো অবিলম্বে বাতিল করা হবে, নাকি ২৪ ঘণ্টার গ্রেস পিরিয়ডের পর বাতিল করা হবে, তা আপনি কনফিগার করতে পারেন।

গুরুত্বপূর্ণ : নতুন সাইনিং সিক্রেটটি রোটেশনের সময় শুধুমাত্র একবার ফেরত দেওয়া হয়। আপনার ভেরিফিকেশন লজিক আপডেট করার আগে এটি নিরাপদে সংরক্ষণ করুন।

পাইথন

from google import genai
from google.genai import types

client = genai.Client()

response = client.webhooks.rotate_signing_secret(
    id="<your_webhook_id>",
    revocation_behavior="REVOKE_PREVIOUS_SECRETS_AFTER_H24",
)

# Store response.secret securely, then update your server's verification config
print("New signing secret generated. Update your server configuration.")

জাভাস্ক্রিপ্ট

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

const client = new GoogleGenAI();

async function rotateSigningSecret() {
  const response = await client.webhooks.rotateSigningSecret(
    "<your_webhook_id>",
    {
      revocation_behavior: "REVOKE_PREVIOUS_SECRETS_AFTER_H24",
    }
  );

  // Store response.secret securely, then update your server's verification config
  console.log("New signing secret generated. Update your server configuration.");
}

rotateSigningSecret();

বিশ্রাম

curl -X POST \
  "https://generativelanguage.googleapis.com/v1/webhooks/<your_webhook_id>/rotate_secret" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GOOGLE_API_KEY" \
  -d '{
    "revocation_behavior": "REVOKE_PREVIOUS_SECRETS_AFTER_H24"
  }'

সার্ভারে ওয়েবহুক অনুরোধগুলি পরিচালনা করুন

যখন আপনার সাবস্ক্রাইব করা কোনো ইভেন্ট ঘটে, তখন আপনার ওয়েবহুক ইউআরএল-এ একটি HTTP POST রিকোয়েস্ট আসবে। পুনরায় চেষ্টা এড়াতে আপনার এন্ডপয়েন্টকে অবশ্যই কয়েক সেকেন্ডের মধ্যে একটি 2xx স্ট্যাটাস কোড দিয়ে সাড়া দিতে হবে। ডেলিভারি নিশ্চিত করতে, জেমিনি এপিআই এক্সপোনেনশিয়াল ব্যাকঅফ ব্যবহার করে ব্যর্থ রিকোয়েস্টগুলো স্বয়ংক্রিয়ভাবে ২৪ ঘণ্টা ধরে পুনরায় চেষ্টা করে।

জেমিনি নিরাপত্তা হেডারের জন্য স্ট্যান্ডার্ড ওয়েবহুকস স্পেসিফিকেশন কঠোরভাবে অনুসরণ করে। স্বাক্ষরিত হেডার সিগনেচার এবং আপনার সংরক্ষিত স্ট্যাটিক সাইনিং সিক্রেট ব্যবহার করে আপনার সার্ভারে পেলোডটি যাচাই করুন। পেলোড তথ্যের জন্য ওয়েবহুক এনভেলপ বিভাগটি দেখুন।

HTTP লিসেনারের জন্য Flask ব্যবহার করে একটি উদাহরণ নিচে দেওয়া হলো:

পাইথন

# pip install flask standardwebhooks
import os
from flask import Flask, request, jsonify
# Standard verification wrapper for Standard Webhook Headers
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)

SIGNING_SECRET = os.environ.get('WEBHOOK_SIGNING_SECRET')

@app.route('/gemini-callback', methods=['POST'])
def gemini_callback():
    payload = request.get_data(as_text=True)
    headers = request.headers

    try:
        wh = Webhook(SIGNING_SECRET)
        event = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return jsonify({"error": "Signature invalid"}), 400

    # Process thin payload contents
    if event.get("type") in ("batch.completed", "video.generated"):
        uri = event['data']['output_file_uri']
        print(f"Batch finished! Results at: {uri}")

    return jsonify({"status": "received"}), 200

if __name__ == "__main__":
    app.run(port=8000)

জাভাস্ক্রিপ্ট

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
const client = new GoogleGenAI({ webhookSecret: process.env.WEBHOOK_SIGNING_SECRET });

// Don't use express.json() because signature verification needs the raw text body
app.use(express.text({ type: "application/json" }));

app.post("/gemini-callback", async (req, res) => {
  const payload = await req.text();
        const headers: Record<string, string> = {};
        req.headers.forEach((value, key) => {
            headers[key] = value;
        });

        try {
            const wh = new Webhook(process.env.WEBHOOK_SIGNING_SECRET);
            const event = wh.verify(payload, headers) as Record<string, any>;

            // Process thin payload contents
            if (event.type === "batch.completed" || event.type === "video.generated") {
                const uri = event.data.output_file_uri;
                console.log(`Job finished! Results at: ${uri}`);
            }

            res.status(200).json({ status: "received" });
        } catch (e) {
            console.error("Webhook verification failed:", e);
            res.status(400).send("Invalid signature");
        }
});

app.listen(8000, () => {
  console.log("Webhook server is running on port 8000");
});

ডাইনামিক ওয়েবহুক

ডাইনামিক ওয়েবহুক আপনাকে একটি ওয়েবহুক এন্ডপয়েন্টকে একটি নির্দিষ্ট রিকোয়েস্ট কনফিগারেশনের সাথে যুক্ত করার সুযোগ দেয়, যা এজেন্ট-অর্কেস্ট্রেশন কিউ-এর জন্য আদর্শ। ডাইনামিক ওয়েবহুক সিমেট্রিক সিক্রেটের পরিবর্তে অ্যাসিমেট্রিক পাবলিক-কী JWKS সিগনেচার ব্যবহার করে।

একটি গতিশীল অনুরোধ জমা দিন

একটি অ্যাসিঙ্ক্রোনাস জব ট্রিগার করার সময় (যেমন, একটি ব্যাচ তৈরি করার সময়) একটি webhook_config যোগ করুন।

পাইথন

from google import genai
from google.genai import types

client = genai.Client()

file_batch_job = client.batches.create(
    model="gemini-3-flash-preview",
    src="files/uploaded_file_id",
    config={
        "display_name": "My Setup",
        "webhook_config": {
            "uris": ["https://my-api.com/gemini-webhook-dynamic"],
            "user_metadata":{"job_group": "nightly-eval", "priority": "high"}
        }
    }
)

জাভাস্ক্রিপ্ট

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

const client = new GoogleGenAI();

async function createBatchWithWebhook() {
  const fileBatchJob = await client.batches.create({
    model: "gemini-3-flash-preview",
    src: "files/uploaded_file_id",
    config: {
      displayName: "My Setup",
      webhookConfig: {
        uris: ["https://my-api.com/gemini-webhook-dynamic"],
        user_metadata: {"job_group": "nightly-eval", "priority": "high"}
      },
    },
  });
}

বিশ্রাম

curl -X POST \
  "https://generativelanguage.googleapis.com/v1/models/gemini-3-flash-preview:batchCreate" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GOOGLE_API_KEY" \
  -d '{
    "src": "files/uploaded_file_id",
    "config": {
      "display_name": "My Setup",
      "webhook_config": {
        "uris": ["https://my-api.com/gemini-webhook-dynamic"],
        "user_metadata": {"job_group": "nightly-eval", "priority": "high"}
      }
    }
  }'

ডায়নামিক স্বাক্ষর যাচাই করুন (JWKS)

ডাইনামিক ওয়েবহুক রিকোয়েস্ট একটি JSON ওয়েব টোকেন (JWT) সিগনেচার নির্গত করে। আপনার লিসেনারকে অবশ্যই সিগনেচারটি এক্সট্র্যাক্ট করতে হবে এবং গুগলের পাবলিক সার্টিফিকেট এন্ডপয়েন্ট ব্যবহার করে তা ভেরিফাই করতে হবে।

পাইথন

import jwt
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

# Google public cert list endpoint
JWKS_URI = "https://generativelanguage.googleapis.com/.well-known/jwks.json"

def load_google_public_key(kid):
    response = requests.get(JWKS_URI).json()
    for key_item in response.get('keys', []):
        if key_item.get('kid') == kid:
            # Convert JWK to Cert wrapper
            return jwt.algorithms.RSAAlgorithm.from_jwk(key_item)
    return None

@app.route('/gemini-webhook-dynamic', methods=['POST'])
def dynamic_handler():
    payload = request.get_data(as_text=True)
    headers = request.headers

    token = headers.get('Webhook-Signature')
    if not token:
        return jsonify({"error": "No signature header"}), 400

    try:
        # Extract kid from JWT header
        unverified_headers = jwt.get_unverified_header(token)
        pub_key = load_google_public_key(unverified_headers.get('kid'))

        if not pub_key:
            return jsonify({"error": "Key cert not found"}), 400

        # Verify Signature against expected audience (e.g., your project client ID)
        event = jwt.decode(
            token,
            pub_key,
            algorithms=["RS256"],
            audience="your-configured-audience"
        )
    except Exception as e:
        return jsonify({"error": "Invalid Dynamic signature", "details": str(e)}), 400

    print("Verified Dynamic payload success.")
    return jsonify({"status": "received"}), 200

জাভাস্ক্রিপ্ট

import { GoogleGenAI } from "@google/genai";
import express from "express";
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const app = express();
app.use(express.text({ type: 'application/json' }));

const client = jwksClient({
  jwksUri: "https://generativelanguage.googleapis.com/.well-known/jwks.json"
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

app.post('/gemini-webhook-dynamic', (req, res) => {
  const token = req.headers['webhook-signature'];

  if (!token) {
    return res.status(400).json({ error: "No signature header" });
  }

  jwt.verify(
    token,
    getKey,
    {
      algorithms: ["RS256"],
      audience: "your-configured-audience"
    },
    (err, decoded) => {
      if (err) {
        return res.status(400).json({ error: "Invalid Dynamic signature", details: err.message });
      }

      console.log("Verified Dynamic payload success.");
      res.status(200).json({ status: "received" });
    }
  );
});

ওয়েবহুক খাম

ব্যান্ডউইথের ভিড় এড়াতে, জেমিনি ওয়েবহুক ডেটা প্রেরণের জন্য একটি থিন পেলোড মডেল ব্যবহার করে। ডেলিভারিগুলো সরাসরি মূল আউটপুট ফাইলের পরিবর্তে স্ট্যাটাসের বিবরণ এবং ফলাফলের পয়েন্টার সম্বলিত একটি স্ন্যাপশট পাঠায়।

এখানে একটি পেলোড ফরম্যাটের উদাহরণ দেওয়া হলো:

{
  "type": "batch.completed",
  "version": "v1",
  "timestamp": "2026-01-22T12:00:00Z",
  "data": {
    "id": "batch_123456",
    "output_file_uri": "gs://my-bucket/results.jsonl",
    "error_count": 0
  }
}

ইভেন্ট ক্যাটালগ রেফারেন্স

সহায়ক কাজগুলোর জন্য নিম্নলিখিত ঘটনাগুলো সংঘটিত হয়:

ইভেন্টের ধরণ ট্রিগার পেলোড আইটেম ( data )
batch.succeeded প্রক্রিয়াকরণ সফলভাবে সম্পন্ন হয়েছে। id , output_file_uri
batch.cancelled ব্যবহারকারী অনুরোধ বাতিল করেছেন id
batch.expired ২৪ ঘণ্টার মধ্যে ব্যাচটি প্রসেস (শেষ) করা হয়নি। id
batch.failed ব্যাচ জব ব্যর্থ হয়েছে (সিস্টেম বা যাচাইকরণ ত্রুটি)। id , error_code , error_message
interaction.requires_action ফাংশন কল, ব্যবহারকারীকে কিছু করতে হবে id
interaction.completed ইন্টারঅ্যাকশন এপিআই-তে LRO সফল হয়েছে id
interaction.failed ইন্টারঅ্যাকশন এপিআই-তে LRO ব্যর্থ হয়েছে (সিস্টেম বা ভ্যালিডেশন ত্রুটি)। id , error_code , error_message
interaction.cancelled ইন্টারঅ্যাকশন এপিআই-তে LRO বাতিল করা হয়েছে id
video.generated ভিডিও জেনারেশন এলআরও সম্পন্ন হয়েছে। file_id , video_uri

সর্বোত্তম অনুশীলন

নির্ভরযোগ্য ও সম্প্রসারণযোগ্য কার্যক্রম নিশ্চিত করতে:

  • কঠোর রিপ্লে সুরক্ষা যাচাই : সমস্ত অনুরোধে একটি webhook-timestamp হেডার থাকে। ৫ মিনিটের বেশি পুরানো পেলোড প্রত্যাখ্যান করতে (রিপ্লে আক্রমণ প্রতিরোধ করার জন্য) আপনার সার্ভার কনফিগারেশন স্তরে সর্বদা এই টাইমস্ট্যাম্পটি যাচাই করুন।
  • অ্যাসিঙ্ক্রোনাসভাবে প্রক্রিয়া করুন : বৈধ স্বাক্ষর শনাক্ত হওয়ার সাথে সাথেই 2xx OK দিয়ে সাড়া দিন এবং অভ্যন্তরীণভাবে পার্সিং অপারেশনগুলিকে সারিবদ্ধ করুন। দীর্ঘক্ষণ লিসেনার ধরে রাখলে একটি ডেলিভারি পুনরায় চেষ্টার চক্র শুরু হবে।
  • ডুপ্লিকেট অপসারণ ব্যবস্থাপনা : স্ট্যান্ডার্ড ওয়েবহুকগুলো "অন্তত একবার" ডেলিভার করে। অধিক কনজেশনযুক্ত ফ্লো-তে সম্ভাব্য ডুপ্লিকেটগুলো সামলাতে সামঞ্জস্যপূর্ণ webhook-id হেডার ব্যবহার করুন।

এরপর কী?

  • ব্যাচ এপিআই : অধিক সংখ্যক এন্ডপয়েন্ট স্বয়ংক্রিয় করতে ওয়েবহুক ব্যবহার করুন।