API ওয়েবহুক নির্দেশিকা

প্রকাশ্য API-তে তৈরি কাজ চূড়ান্ত অবস্থায় পৌঁছানোর পর Rivya যেন আপনার সার্ভারকে জানায়, এমন সংযোগ দরকার হলে API ওয়েবহুক ব্যবহার করুন।

GET /api/v1/generations/{taskId} বারবার যাচাই করার পদ্ধতি এখনও সমর্থিত। উৎপাদন ব্যবস্থা ঘটনাভিত্তিক সরবরাহ চাইলে ওয়েবহুক স্বাক্ষরিত প্রত্যুত্তরের ব্যবস্থা যোগ করে।

প্রয়োজনীয় অনুমতির পরিসর

ওয়েবহুক পরিচালনার জন্য API কীতে থাকতে হবে:

webhooks:manage

বিন্যাসে তৈরি নতুন কীতে পূর্বনির্ধারিতভাবে এই অনুমতির পরিসর থাকে।

এন্ডপয়েন্ট তৈরি করুন

POST /api/v1/webhooks

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

উত্তরে signing_secret শুধু একবারই থাকে:

{
  "id": "whend_...",
  "object": "webhook_endpoint",
  "name": "Production webhook",
  "url": "https://example.com/rivya/webhook",
  "event_types": ["generation.succeeded", "generation.failed"],
  "status": "active",
  "secret_preview": "whsec_12...abc123",
  "signing_secret": "whsec_...",
  "last_success_at": null,
  "last_failure_at": null,
  "failure_count": 0,
  "created_at": "2026-05-11T00:00:00.000Z",
  "updated_at": "2026-05-11T00:00:00.000Z",
  "disabled_at": null,
  "revoked_at": null
}

সম্পূর্ণ গোপন মানটি আপনার সার্ভারে সংরক্ষণ করুন। হারিয়ে ফেললে বদলানোর সংযোগবিন্দুতে কল করে গ্রহণকারী হালনাগাদ করুন।

URL-এর নিয়ম

সংযোগবিন্দুর URL অবশ্যই HTTPS হতে হবে। Rivya পরিচয়পত্র, খণ্ডচিহ্ন, localhost নাম, স্থানীয় নেটওয়ার্কের ঠিকানা, ব্যক্তিগত IP সীমা, লুপব্যাক ও সংরক্ষিত ঠিকানাযুক্ত URL প্রত্যাখ্যান করে।

Rivya সবসময় পাঠায়:

• POST

• Content-Type: application/json

• ব্যবহারকারী-নিয়ন্ত্রিত আলাদা অনুরোধ হেডার নয়

• স্বয়ংক্রিয়ভাবে অন্য ঠিকানায় যাওয়া নয়

• সরবরাহের জন্য স্বল্প সময়সীমা

ইভেন্ট

বর্তমান ঘটনার ধরন:

• generation.succeeded

• generation.failed

ওয়েবহুকের তথ্যগুচ্ছ অবস্থার সংযোগবিন্দুর একই প্রকাশ্য তৈরি-ফল রূপান্তরকারী ব্যবহার করে।

{
  "id": "evt_...",
  "type": "generation.succeeded",
  "api_version": "2026-05-11",
  "created_at": "2026-05-11T00:00:00.000Z",
  "data": {
    "generation": {
      "id": "task_public_id",
      "status": "succeeded",
      "model": "z-image",
      "reserved_credits": 1,
      "final_credits": 1,
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:01:00.000Z",
      "result": {
        "primary_url": "https://...",
        "urls": ["https://..."]
      },
      "error": null
    }
  }
}

ডেলিভারি হেডার

প্রতিটি ডেলিভারিতে থাকে:

Rivya-Webhook-Id: evt_...
Rivya-Webhook-Timestamp: 1778467200
Rivya-Webhook-Signature: v1=<hex-hmac-sha256>
Rivya-Webhook-Attempt: 1
Rivya-Webhook-Endpoint-Id: whend_...
Rivya-Request-Id: req_...

স্বাক্ষরের ইনপুট:

${timestamp}.${rawBody}

অ্যালগরিদম:

সংযোগবিন্দুর স্বাক্ষর গোপনীয়তা দিয়ে HMAC-SHA256

পুরোনো সময়মুদ্রাসহ অনুরোধ প্রত্যাখ্যান করুন। পাঁচ মিনিটের সহনসীমা ব্যবহারিক পূর্বনির্ধারিত মান।

JavaScript-এ যাচাই

import crypto from "node:crypto";

function verifyRivyaWebhook({ rawBody, headers, signingSecret }) {
  const timestamp = headers["rivya-webhook-timestamp"];
  const signature = headers["rivya-webhook-signature"] || "";
  const actual = signature.split(",").find((part) => part.startsWith("v1="))?.slice(3);
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!actual) return false;
  return crypto.timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
}

Python-এ যাচাই

import hmac
import hashlib

def verify_rivya_webhook(raw_body: str, headers: dict, signing_secret: str) -> bool:
    timestamp = headers.get("rivya-webhook-timestamp", "")
    signature = headers.get("rivya-webhook-signature", "")
    actual = next((part[3:] for part in signature.split(",") if part.startswith("v1=")), "")
    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return bool(actual) and hmac.compare_digest(actual, expected)

এন্ডপয়েন্ট পরিচালনা

GET /api/v1/webhooks
GET /api/v1/webhooks/{endpointId}
PATCH /api/v1/webhooks/{endpointId}
DELETE /api/v1/webhooks/{endpointId}
POST /api/v1/webhooks/{endpointId}/rotate-secret

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..."

curl https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..."

curl -X PATCH https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../rotate-secret \
  -H "Authorization: Bearer rvya_sk_..."

DELETE /api/v1/webhooks/{endpointId} সংযোগবিন্দুটি নিষ্ক্রিয় করে। এটি সরবরাহের ইতিহাস মুছে দেয় না।

ডেলিভারির রেকর্ড

সাম্প্রতিক ঘটনাগুলোর তালিকা নিন:

GET /api/v1/webhook-events

curl https://rivya.ai/api/v1/webhook-events \
  -H "Authorization: Bearer rvya_sk_..."

সংযোগবিন্দুটির সরবরাহের চেষ্টাগুলোর তালিকা নিন:

GET /api/v1/webhooks/{endpointId}/deliveries

curl https://rivya.ai/api/v1/webhooks/whend_.../deliveries \
  -H "Authorization: Bearer rvya_sk_..."

সরবরাহের নথিতে অবস্থা, HTTP অবস্থা, চেষ্টার সংখ্যা, অনুরোধ ID, সময়কাল, সংক্ষিপ্ত প্রতিক্রিয়ার অংশ ও প্রকাশ্য ত্রুটির ঘর থাকে।

পরীক্ষামূলক ইভেন্ট

নিরাপদ পরীক্ষার পেলোড পাঠান:

POST /api/v1/webhooks/{endpointId}/test

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../test \
  -H "Authorization: Bearer rvya_sk_..."

পরীক্ষার ঘটনায় webhook.test ব্যবহার করা হয়। এটি তৈরির কাজ তৈরি বা ক্রেডিট খরচ করে না এবং বাস্তব ফলাফলের URL-ও রাখে না।

পুনরায় চেষ্টার নীতি

Rivya HTTP 2xx-কে সফল প্রতিক্রিয়া হিসেবে ধরে।

ব্যর্থতার মধ্যে নেটওয়ার্ক ত্রুটি, সময়সীমা পেরোনো, পুনর্নির্দেশ প্রতিক্রিয়া ও 2xx নয় এমন প্রতিক্রিয়া আছে। Rivya সর্বোচ্চ পাঁচবার চেষ্টা করে:

• সঙ্গে সঙ্গে

• 1 মিনিট পরে

• 5 মিনিট পরে

• 30 মিনিট পরে

• 2 ঘণ্টা পরে

শেষ চেষ্টার পরে ঘটনাটি failed হিসেবে চিহ্নিত হয়।

ওয়েবহুক সরবরাহ ব্যর্থ হলে তৈরির অবস্থা, ক্রেডিট, ফেরত বা কাজের ইতিহাস বদলায় না।

নিরাপত্তা যাচাই-তালিকা

• ব্যবসায়িক যুক্তি বিশ্লেষণের আগে HMAC স্বাক্ষর যাচাই করুন।

• পুরোনো সময়মুদ্রা প্রত্যাখ্যান করুন।

• পরীক্ষার ঘটনাকে তৈরির ঘটনা থেকে আলাদা রাখুন।

• সম্পূর্ণ স্বাক্ষর গোপনীয়তা লগে লিখবেন না।

• গ্রহণকারী ঘটনাটি গ্রহণ করার পরেই শুধু 2xx ফেরত দিন।

• হিসাব মেলানোর বিকল্প হিসেবে বারবার অবস্থা যাচাই রাখুন।

সম্পর্কিত পৃষ্ঠা

• তৈরির কাজ শুরু করুন

• তৈরির অবস্থা

• API ত্রুটি ও সীমা

• OpenAPI ও স্কিমা চুক্তি