ওয়েবহুকস
ওয়েবহুক URL কনফিগার করা থাকলে, একটি ফাইল অনুবাদ জব (/jobs) শেষ হলে (সফলভাবে বা না হলে) আপনার সার্ভারকে নোটিফাই করা হবে। POST /jobs/{id}/cancel দিয়ে বাতিল করা জবগুলো কোনো কলব্যাক পাঠায় না। ডকুমেন্ট অপারেশন এবং মিডিয়া জবগুলোর জন্য, তাদের নিজস্ব কোয়েরি এন্ডপয়েন্টগুলো পোল করুন।
ওয়েবহুক পরিচালনা করুন
Section titled “ওয়েবহুক পরিচালনা করুন”এপিআই-এর মাধ্যমে পরিচালিত, প্রতি ব্যবহারকারীর জন্য সর্বোচ্চ ৩টি:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteউদাহরণ তৈরি করুন:
curl -X POST https://omnidoc.top/api/v1/webhooks \ -H "X-API-Key: sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/omnidoc", "secret": "your-signing-secret", "events": ["job.completed"], "description": "Production callback" }'URLটি অবশ্যই সর্বজনীন ইন্টারনেট থেকে অ্যাক্সেসযোগ্য হতে হবে, বিশেষ করে HTTPS এর মাধ্যমে; ব্যক্তিগত নেটওয়ার্ক, স্থানীয় ঠিকানা এবং ত্রুটিপূর্ণ URL ফলাফল হিসেবে 400 দেখায়। PATCH কমান্ড url, secret, events, description এবং status (active / disabled) পরিবর্তন করতে পারে।
কলব্যাক ফরম্যাট
Section titled “কলব্যাক ফরম্যাট”POST your-webhook-urlContent-Type: application/jsonX-Webhook-Event: job.completedX-Webhook-Timestamp: 1782900150X-Webhook-Signature: sha256=...{ "event": "job.completed", "timestamp": 1782900150, "data": { "job_id": "q3f8s6c2a9m1k4tx", "status": "completed", "file_name": "report.docx", "char_count": 12840 }}| ঘটনা | যখন |
|---|---|
job.completed | একটি কাজ শেষ হয়; data.status হল completed বা failed |
ব্যর্থ কাজগুলিও job.completed ইভেন্ট ব্যবহার করে; তাদের আলাদা করতে data.status == "failed" এবং ঐচ্ছিক data.error ব্যবহার করুন। সফল কাজগুলিতে error ফিল্ড থাকে না। data.char_count হল অনুবাদের অক্ষরসংখ্যা, ব্যর্থ কাজের জন্য 0।
events শুধুমাত্র job.completed এবং * (সকল ইভেন্ট) গ্রহণ করে; অন্যান্য মান বা খালি তালিকা প্রদান করলে 422 ত্রুটি ফেরত দেয়। PATCH অনুরোধে, যে ক্ষেত্রগুলো পরিবর্তন করছেন না তা উপেক্ষা করুন; null প্রেরণ করলেও 422 ত্রুটি ফেরত দেয়।
স্বাক্ষরটি যাচাই করুন
Section titled “স্বাক্ষরটি যাচাই করুন”যখন আপনি ওয়েবহুকে secret সেট করেন, তখন প্রতিটি কলব্যাকে X-Webhook-Signature থাকে। এটি HMAC-SHA256 ব্যবহার করে র raw রিকোয়েস্ট বডি-এর উপর যাচাই করুন:
import hashlibimport hmacimport jsonimport time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict: if not verify_webhook(payload, signature, secret): raise ValueError("invalid signature") event = json.loads(payload) if abs(time.time() - event["timestamp"]) > tolerance: raise ValueError("stale event") return eventসিগনেচারটি শুধুমাত্র বডিকে কভার করে, হেডারগুলিকে নয়। রিপ্লে সুরক্ষার জন্য, সিগনেচার পাস হওয়ার পরে বডিতে timestamp চেক করুন (এটি X-Webhook-Timestamp এর সমান, তবে শুধুমাত্র বডির মানটিই সাইন করা হয়), এবং data.job_id ও data.status দ্বারা ডুপ্লিকেট অপসারণ করুন। রিট্রাইগুলি প্রথম ডেলিভারির বডিকে অপরিবর্তিত রেখে পুনরায় প্রেরণ করে, একই timestamp সহ, এবং শেষ রিট্রাই প্রথম ডেলিভারির প্রায় 8.6 ঘণ্টা পরে আসে, তাই উইন্ডোটিকে এর চেয়ে ছোট করবেন না (উদাহরণে 12 ঘণ্টা ব্যবহার করা হয়েছে)।
ডেলিভারি
Section titled “ডেলিভারি”- ডেলিভারি সফল হিসেবে গণ্য হওয়ার জন্য রিসিভারকে 15 সেকেন্ডের মধ্যে
2xxফেরত পাঠাতে হবে; রিডাইরেক্টগুলো অনুসরণ করা হয় না। - ব্যর্থ হওয়া ডেলিভারি (সময় শেষ হওয়া, সংযোগ ত্রুটি বা
2xxছাড়া) স্বয়ংক্রিয়ভাবে পুনরায় চেষ্টা করা হয়: আগের ব্যর্থতার 1 মিনিট, 5 মিনিট, 30 মিনিট, 2 ঘণ্টা এবং 6 ঘণ্টা পরে, প্রতি ইভেন্টে সর্বোচ্চ 6টি ডেলিভারি, তারপর আর কোনো চেষ্টা হয় না। - পুনরায় চেষ্টা করার সময়, বডিটি অপরিবর্তিত থাকে (
timestamp,dataএবং সিগনেচার প্রথম ডেলিভারির সাথে মিলে যায়; যদি এর মধ্যেsecretপরিবর্তিত হয়, তবে নতুনsecretদ্বারা স্বাক্ষর করা হয়); ইতিমধ্যে ডেলিভারি দেওয়া ইভেন্টগুলো আবার প্রেরণ করা হয় না। - যখন কোনো ওয়েবহুক নিষ্ক্রিয় করা হয়, মুছে ফেলা হয় বা আর সেই ইভেন্টের জন্য সাবস্ক্রাইব করা থাকে না, তখন এর অপেক্ষমান পুনরায় চেষ্টাগুলো বাতিল করা হয়।
- রিসিভারগুলো
data.job_idএবংdata.statusঅনুসারে ইভেন্টগুলোকে আইডেমপটেন্টলি পরিচালনা করবে এবং সেগুলোকে নিরাপদে সংরক্ষণের পর দ্রুত প্রতিক্রিয়া জানাবে। - একটি অ্যাকাউন্টের একাধিক ওয়েবহুক সমান্তরালভাবে প্রেরণ করা হয়; একটি ধীরগতির গ্রাহক অন্যগুলোকে বাধাগ্রস্ত করে না।
- টানা 10টি ব্যর্থ ডেলিভারির (পুনরায় চেষ্টাসহ) পর, ওয়েবহুকটি স্বয়ংক্রিয়ভাবে নিষ্ক্রিয় হয়ে যায়; গ্রাহক ঠিক হওয়ার পর
PATCHদিয়ে এটিকে পুনরায় সক্রিয় করুন। GET /api/v1/webhooksপ্রতিটি ওয়েবহুকের সর্বশেষ ট্রিগার সময়, স্ট্যাটাস কোড এবং পরপর ত্রুটির সংখ্যা দেখায়।