ওয়েবহুক (বহির্গামী)

ওয়েবহুক হলো ইন্টিগ্রেশনের «পুশ» অংশ: আপনার সিস্টেম FreeMaint-কে বারবার জিজ্ঞাসা করার বদলে, কিছু ঘটলেই FreeMaint আপনার URL-এ POST পাঠায়। কোম্পানি সেটিংস > ওয়েবহুক (/company-settings/webhooks) থেকে সেট করুন। Starter প্ল্যান থেকে উপলব্ধ (দিনে ১০০ ডেলিভারি; Business ও তার উপরে সীমাহীন)।

উপলব্ধ ইভেন্ট

• work_order.created — একটি কাজের নির্দেশনা তৈরি হয়েছে
• work_order.completed — একটি কাজের নির্দেশনা «সম্পন্ন» হয়েছে
• work_order.status_changed — একটি কাজের নির্দেশনা যেকোনো স্ট্যাটাসে গেছে; পেলোডে new_status থাকে। অপরিবর্তিত work_order.completed-এর পাশাপাশি এটিও ট্রিগার হয়
• request.created — একটি রক্ষণাবেক্ষণ অনুরোধ জমা পড়েছে
• request.status_changed — একটি অনুরোধ অনুমোদিত, প্রত্যাখ্যাত বা বাতিল হয়েছে
• part.low_stock — একটি পার্টস পুনঃক্রয় সীমায় বা তার নিচে নেমেছে
• part.out_of_stock — একটি পার্টস শূন্যে নেমেছে
• part.low_stock_summary — প্রতি কোম্পানিতে দিনে একটি সারসংক্ষেপ, যাতে পুনঃক্রয় সীমায় বা তার নিচে থাকা যন্ত্রাংশগুলি থাকে — যেগুলি কখনও নড়েনি সেগুলিও
• part.out_of_stock_summary — শূন্যে থাকা যন্ত্রাংশের জন্য সেই একই দৈনিক সারসংক্ষেপ
• part.consumed — একটি পার্টস কাজের নির্দেশনায় ব্যবহৃত হয়েছে, বা ফেরত এসেছে
• compliance.chain_divergence — নিরীক্ষার হ্যাশ-চেইন ভেঙেছে (Enterprise)
• asset.downtime_started — একটি যন্ত্র বন্ধের রেকর্ড খোলা হয়েছে
• asset.downtime_ended — একটি যন্ত্র বন্ধের রেকর্ড বন্ধ করা হয়েছে; সময়কাল এখন হিসাবে তোলা যাবে
• report.daily_summary — দিনের সম্পন্ন কাজ, আপনার বেছে নেওয়া সময়ে দিনে একবার
• purchase_order.created — একটি ক্রয়াদেশ তৈরি হয়েছে; পেলোডে ক্রয়াদেশটি (reference, status, total_cost, currency, expected_date, erp_reference) ও তার সরবরাহকারী থাকে
• purchase_order.status_changed — একটি ক্রয়াদেশের স্ট্যাটাস বদলেছে (অনুমোদিত, অর্ডার করা, বাতিল…); পেলোডে previous_status ও new_status থাকে
• purchase_order.received — একটি ক্রয় আদেশের বিপরীতে একটি ডেলিভারি গ্রহণ করা হয়েছে (আংশিকসহ প্রতিটি ডেলিভারিতে পাঠানো হয়); পেলোডে প্রতিটি লাইন quantity_ordered, quantity_received (এই ডেলিভারি), quantity_received_total ও quantity_remaining সহ তালিকাভুক্ত থাকে, সঙ্গে receipt_id, fully_received ও closed_short; পণ্য প্রত্যাশিত থাকা পর্যন্ত new_status হলো PARTIALLY_RECEIVED এবং সম্পূর্ণ বা বন্ধ হলে RECEIVED

part.consumed — ERP-তে স্টক প্রতিফলিত করা

অন্য কোনো সিস্টেম (ERP, বিলিং, ইনভেন্টরি, হিসাবরক্ষণ) যখন রক্ষণাবেক্ষণে প্রকৃতপক্ষে কী ব্যবহৃত হয়েছে তা প্রতিফলিত করবে, তখন এই ইভেন্টেই সাবস্ক্রাইব করবেন। quantity চিহ্নসহ: কাজে ইস্যু হলে ঋণাত্মক, কাজের নির্দেশনা থেকে সরিয়ে ফেরত দিলে ধনাত্মক — ফলে FreeMaint-এ বাতিল করলে অপর প্রান্তে মিলে যাওয়া ফেরত নথি তৈরি হয়। stock_movement_id পুনঃচেষ্টা ও পুনঃপ্রেরণেও অপরিবর্তিত থাকে: একে idempotency কী হিসেবে ব্যবহার করলে একই ইস্যু কখনোই দুবার পোস্ট হবে না। তথ্য দুই দিকে চললে একটি বিষয় জেনে রাখা দরকার: GraphQL-এর adjustStock মিউটেশন এই ইভেন্টটি চালু করে না। এটি ইচ্ছাকৃত — আপনার নিজের সিস্টেম FreeMaint-এ যে স্টক সংশোধন লেখে, তা প্রতিধ্বনি হয়ে আপনার কাছে ফিরে এসে দুবার হিসাব হওয়া উচিত নয়। কেবল FreeMaint-এর ভিতরে কোনো কাজের নির্দেশনায় নথিভুক্ত ব্যবহারই part.consumed তৈরি করে। যন্ত্রাংশে custom_reference-ও থাকে: এটির জন্য আপনার নিজস্ব কোড, অর্থাৎ createPart বা updatePart দিয়ে সেট করা customReference, যাতে ক্যাটালগ পরিচালনাকারী সিস্টেম FreeMaint আইডির কোনো টেবিল ছাড়াই প্রতিটি লাইন মেলাতে পারে।

{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "বিয়ারিং 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "টি" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "বিয়ারিং প্রতিস্থাপন" }, "asset": { "id": 91, "name": "সেপারেটর ২" }, "location": { "id": 7, "name": "প্ল্যান্ট গুদাম" }, "user": { "id": 5627, "name": "এ. টেকনিশিয়ান" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }

ডেলিভারি ও স্বাক্ষর

প্রতিটি ডেলিভারি একটি POST, সঙ্গে JSON বডি এবং t=<unix সেকেন্ড>,v1=<hex> আকারের X-FreeMaint-Signature হেডার, যেখানে v1 হলো আপনার ওয়েবহুক সিক্রেট কী দিয়ে «<t>.<কাঁচা বডি>» স্ট্রিং-এর HMAC-SHA256। যাচাই করুন কাঁচা বডির বিপরীতে, কোনো JSON পার্সিং বা পুনঃসিরিয়ালাইজেশনের আগে। আমরা X-FreeMaint-Event ও X-FreeMaint-Delivery-Id-ও পাঠাই। 2xx মানে ডেলিভারি সফল; নেটওয়ার্ক ত্রুটি ও 5xx সর্বোচ্চ ৩ বার এক্সপোনেনশিয়াল ব্যাকঅফসহ পুনরায় চেষ্টা করা হয় (প্রায় ২ সে., ৪ সে., ৮ সে.); 4xx-কে স্থায়ী প্রত্যাখ্যান ধরা হয় এবং পুনরায় চেষ্টা করা হয় না।

ডেলিভারি পুনঃপ্রেরণ

প্রতিটি চেষ্টা ওয়েবহুকের ডেলিভারি ইতিহাসে স্ট্যাটাস ও রেসপন্স কোডসহ থাকে। শেষ হয়ে যাওয়া যেকোনো ডেলিভারি সেখান থেকে পুনরায় পাঠানো যায়: সংরক্ষিত পেলোড হুবহু আবার যায়, তাই তার ভেতরের ব্যবসায়িক কী (stock_movement_id সহ) একই থাকে এবং সঠিকভাবে ডিডুপ্লিকেট করা রিসিভার দুবার পোস্ট করবে না। আপনার এন্ডপয়েন্ট বন্ধ থাকলে বা ভুলবশত অনুরোধ প্রত্যাখ্যান করলে এভাবেই ঘাটতি পূরণ করবেন।

ছবি (ঐচ্ছিক)

কোনো ওয়েবহুকে "ছবি অন্তর্ভুক্ত করুন" চালু থাকলে (ডিফল্টভাবে বন্ধ), "work_order" ও "request" অবজেক্টে একটি "photos" অ্যারে থাকে: JPG, PNG, GIF বা WebP ছবির সর্বোচ্চ 4টি HTTPS লিংক, নতুনগুলো আগে। প্রতিটি লিংক 7 দিন ধরে সাইন ইন ছাড়াই ছবিটি খোলে, তাই আরও বেশি সময় দরকার হলে ফাইলটি নিজের সিস্টেমে সংরক্ষণ করুন। পুনরায় পাঠালে একই লিংক যায়। অন্য ইভেন্ট ও অন্য ওয়েবহুক অপরিবর্তিত থাকে। "work_order.created" ও "request.created"-এর ক্ষেত্রে "ছবি অন্তর্ভুক্ত করুন" চালু থাকা ওয়েবহুক ইভেন্টের 90 সেকেন্ড পরে পাঠানো হয় ("timestamp" ফিল্ড ইভেন্টের সময়ই রাখে), যাতে রেকর্ডের ঠিক পরে আপলোড করা ছবিগুলোও থাকে।

URL-এর শর্ত

• কেবল https:// — সাধারণ http প্রত্যাখ্যাত
• কেবল পোর্ট 443 বা 8443
• হোস্ট অবশ্যই পাবলিকভাবে পৌঁছানোর যোগ্য হতে হবে — loopback, প্রাইভেট ও CGNAT রেঞ্জ প্রত্যাখ্যাত
• URL-এ কোনো ক্রেডেনশিয়াল নয় (https://user:pass@host প্রত্যাখ্যাত)
• যে সিস্টেম কেবল আপনার নিজের নেটওয়ার্কে আছে, তার সামনে একটি পাবলিক এন্ডপয়েন্ট বা রিলে (n8n, Make, Zapier) লাগবে

সীমা

• Starter — প্রতি কোম্পানিতে দিনে ১০০ ডেলিভারি
• Business — সীমাহীন
• Enterprise — সীমাহীন
• গণনা হয় ডেলিভারি চেষ্টা ধরে: একই ইভেন্টে সাবস্ক্রাইব করা তিনটি ওয়েবহুক তিন একক খরচ করে
• দৈনিক কাউন্টার 00:00 UTC-তে রিসেট হয়