Webhooks — আপনার সিস্টেমে রিয়েল-টাইম মডারেশন ইভেন্ট

1Webhook কী করে

API পোল করার বদলে, আপনি একটি URL নিবন্ধন করেন এবং আপনার গ্রুপে কিছু ঘটলেই Telm এটিতে একটি স্বাক্ষরিত HTTP POST পাঠায়। এভাবেই আপনি রিয়েল টাইমে আপনার নিজের সিস্টেমে — একটি ড্যাশবোর্ড, একটি ডেটা ওয়্যারহাউস, একটি সতর্কতা চ্যানেল — মডারেশন ইভেন্ট পান।

আপনি API-এর মাধ্যমে webhook এন্ডপয়েন্ট পরিচালনা করেন: একটি URL নিবন্ধন করুন, কোন ইভেন্টে সাবস্ক্রাইব করবেন বেছে নিন, ঐচ্ছিকভাবে নির্দিষ্ট গ্রুপে সীমাবদ্ধ করুন, একটি টেস্ট পিং পাঠান, এবং সাম্প্রতিক ডেলিভারি লগ পড়ুন।

2পুশ কেন পোলিংয়ের চেয়ে ভালো

আপনি নতুন ইভেন্ট খুঁজতে একটি টাইমারে জার্নাল এন্ডপয়েন্ট কল করতে পারেন, তবে এটি ল্যাটেন্সি যোগ করে, কোটা খরচ করে, এবং কিছু ঘটার সঠিক মুহূর্তটি মিস করতে পারে। Webhook মডেলটি উল্টে দেয়: একটি ইভেন্ট ঘটামাত্র Telm আপনাকে জানায়, তাই আপনার সিস্টেম সেকেন্ডে সাড়া দেয়।

সাধারণ ব্যবহারের মধ্যে রয়েছে আপনার নিজের অ্যাডমিন টুলে ব্যান মিরর করা, একটি রেইড শনাক্ত হলে একটি টিম চ্যানেলকে সতর্ক করা, অ্যানালিটিক্সে শনাক্তকরণ স্ট্রিম করা, বা একজন সদস্য জয়েন বা লিভ করলে একটি ওয়ার্কফ্লো চালু করা।

• রিয়েল-টাইম: আপনি একটি ইভেন্ট সম্পর্কে ঘটার সঙ্গে সঙ্গে জানেন, আপনার পরবর্তী পোলে নয়।
• কার্যকর: আপনার দৈনিক কোটা খেয়ে ফেলা কোনো বারবার পড়া নেই।
• সম্পূর্ণ: ডেলিভারি পুনরায় চেষ্টা করা হয়, তাই আপনার দিকে একটি সংক্ষিপ্ত বিভ্রাট ইভেন্ট হারায় না।

3আপনি যে ইভেন্টে সাবস্ক্রাইব করতে পারেন

সাতটি সাবস্ক্রাইবযোগ্য ইভেন্ট টাইপ আছে, স্প্যাম রায়, শাস্তি ও সদস্যপদ পরিবর্তন কভার করে। একটি একক মডারেট করা বার্তা একাধিক ইভেন্ট তৈরি করতে পারে — একটি স্প্যাম বার্তা যা একটি ব্যানে শেষ হয় তা spam.detected ও user.banned দুটোই নির্গত করে।

• spam.detected — ইঞ্জিন একটি বার্তা স্প্যাম হিসেবে ফ্ল্যাগ করেছে।
• message.suspicious — একটি স্কোরসহ একটি শ্যাডো (মনিটরিং-মোড) শনাক্তকরণ।
• user.banned — একজন সদস্য ব্যান হয়েছেন।
• user.kicked — একজন সদস্য সরানো হয়েছে।
• user.muted — একজন সদস্য মিউট হয়েছেন।
• user.joined — একজন সদস্য গ্রুপে জয়েন করেছেন।
• user.left — একজন সদস্য গ্রুপ ছেড়েছেন।

4পেলোড এনভেলপ

প্রতিটি ডেলিভারি একটি JSON এনভেলপ যাতে একটি ছোট, স্থিতিশীল শীর্ষ-স্তরের ফিল্ড সেট এবং ভেতরে একটি ইভেন্ট-নির্দিষ্ট data অবজেক্ট থাকে। বিস্তারিত পার্স না করেই আপনি type ও time-এ রাউট করতে পারেন যতক্ষণ না প্রয়োজন হয়।

• id — একটি অনন্য ডেলিভারি id; একই ইভেন্টের পুনঃডেলিভারি একই id পুনরায় ব্যবহার করে, যা দিয়ে আপনি ডিডুপ্লিকেট করেন।
• type — ইভেন্ট টাইপ, উপরের সাতটির একটি।
• created_at — ইভেন্টটি কখন ঘটেছিল, RFC3339 UTC-তে।
• group_id — ইভেন্টটি যে গ্রুপের অন্তর্গত (প্রযোজ্য হলে)।
• data — একটি ইভেন্ট-নির্দিষ্ট অবজেক্ট: স্প্যাম ইভেন্টের জন্য বার্তা ও রায় বিবরণ, সদস্যপদ ইভেন্টের জন্য সদস্য বিবরণ।

5ডেলিভারি সত্যিই Telm থেকে কিনা যাচাই করা

প্রতিটি ডেলিভারি স্বাক্ষরিত যাতে আপনার সার্ভার নিশ্চিত করতে পারে অনুরোধটি সত্যিই Telm থেকে এসেছে এবং পথে বিকৃত হয়নি। পেলোডে আস্থা রাখার আগে স্বাক্ষরটি যাচাই করুন, এবং যা মেলে না তা প্রত্যাখ্যান করুন।

স্বাক্ষরটি হলো টাইমস্ট্যাম্প ও কাঁচা অনুরোধ বডির একটি HMAC-SHA256, আপনার এন্ডপয়েন্ট স্বাক্ষর সিক্রেট দিয়ে কী করা। যাচাই করতে, টাইমস্ট্যাম্প হেডার ও আপনি যে সঠিক বাইট পেয়েছেন তার উপর HMAC পুনরায় গণনা করুন, এবং এটি স্বাক্ষর হেডারের সঙ্গে তুলনা করুন।

• X-Telm-Signature — স্বাক্ষর, v1 এর পরে টাইমস্ট্যাম্প ও বডি যুক্ত করা হেক্স HMAC-SHA256 হিসেবে ফরম্যাট করা।
• X-Telm-Timestamp — যে ইউনিক্স-সেকেন্ড টাইমস্ট্যাম্প স্বাক্ষরিত, যাতে আপনি বাসি বা রিপ্লে করা ডেলিভারি প্রত্যাখ্যান করতে পারেন।
• X-Telm-Event — ইভেন্ট টাইপ, এবং X-Telm-Delivery — ডিডুপ্লিকেশনের জন্য ডেলিভারি id।
• স্বাক্ষর সিক্রেটটি এন্ডপয়েন্ট তৈরির সময় একবারই দেখানো হয় এবং whsec_ দিয়ে শুরু হয়। এটি নিরাপদে সংরক্ষণ করুন; এটিই একমাত্র জিনিস যা প্রমাণ করে একটি ডেলিভারি খাঁটি।

6নির্ভরযোগ্য, ডিডুপ্লিকেট করা ডেলিভারি

ডেলিভারি অন্তত-একবার: Telm নিশ্চিত করে যে একটি ইভেন্ট আপনার কাছে পৌঁছায়, অর্থাৎ একই ইভেন্ট মাঝেমধ্যে দুবার আসতে পারে। যেহেতু প্রতিটি পুনঃডেলিভারি একই ডেলিভারি id পুনরায় ব্যবহার করে, আপনি যে id প্রক্রিয়া করেছেন সেগুলো সংরক্ষণ করে ও পুনরাবৃত্তি এড়িয়ে ডিডুপ্লিকেট করেন।

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

• একটি 2xx স্ট্যাটাস দিয়ে দ্রুত সাড়া দিন; স্বীকার করার পর ভারী কাজ অ্যাসিনক্রোনাসভাবে করুন।
• ডেলিভারি id-তে ডিডুপ্লিকেট করুন — কখনও পেলোড বিষয়বস্তুতে নয়।
• একটি এন্ডপয়েন্ট যা একটি 72-ঘণ্টার উইন্ডোর মধ্যে কোনো সাফল্য ছাড়া পরপর প্রায় বিশবার ব্যর্থ হয় তা স্বয়ংক্রিয়ভাবে নিষ্ক্রিয় হয়; আপনার সার্ভার সুস্থ হলে এটি পুনরায় সক্রিয় করুন।

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

আপনি API-এর মাধ্যমে webhook এন্ডপয়েন্ট নিবন্ধন, সম্পাদনা ও অপসারণ করেন। আপনি যখন একটি তৈরি করেন আপনি স্বাক্ষর সিক্রেটটি ঠিক একবার পান, সাবস্ক্রাইব করার ইভেন্ট বেছে নেন, এবং ঐচ্ছিকভাবে এটি নির্দিষ্ট গ্রুপে সীমাবদ্ধ করেন। একটি টেস্ট কল একটি স্বাক্ষরিত পিং পাঠায় যাতে বাস্তব ট্রাফিক শুরুর আগে আপনি আপনার যাচাই কাজ করে কিনা নিশ্চিত করতে পারেন।

প্রতিটি এন্ডপয়েন্ট একটি ডেলিভারি লগ রাখে যা আপনি ফিরে পড়ে দেখতে পারেন কী পাঠানো হয়েছে, কখন, এবং এটি সফল হয়েছে কিনা — পরবর্তী সরাসরি ইভেন্টের জন্য অপেক্ষা না করে একটি রিসিভার ডিবাগ করতে সুবিধাজনক।

• একটি এন্ডপয়েন্ট তৈরি করুন এবং whsec_ সিক্রেটটি সঙ্গে সঙ্গে কপি করুন।
• আপনার স্বাক্ষর যাচাই এন্ড টু এন্ড যাচাই করতে একটি টেস্ট পিং পাঠান।
• একটি এন্ডপয়েন্ট একটি গ্রুপে সীমাবদ্ধ করুন বা আপনি পরিচালনা করেন এমন সব গ্রুপে খোলা রাখুন।
• সাম্প্রতিক প্রচেষ্টা ও তাদের ফলাফল পরিদর্শন করতে ডেলিভারি লগ পড়ুন।

8সেরা অনুশীলন ও সাধারণ ভুল

একটি মজবুত রিসিভার কয়েকটি নিয়ম মেনে চলে যা সবচেয়ে সাধারণ সমস্যাগুলো প্রতিরোধ করে।

• কাঁচা বডি বাইটের উপর স্বাক্ষর যাচাই করুন — প্রথমে JSON-এ পার্স করে পুনরায় সিরিয়ালাইজ করলে বাইট পরিবর্তন হয়ে যাচাই ভেঙে যেতে পারে।
• 2xx দ্রুত ফেরত দিন এবং পরে প্রক্রিয়া করুন; একটি ধীর হ্যান্ডলার টাইমআউট ও অপ্রয়োজনীয় পুনঃচেষ্টা ঘটায়।
• হ্যান্ডলিং idempotent করুন যাতে একটি পুনঃডেলিভার করা ইভেন্ট দ্বিগুণ গণনা না করে।
• একটি প্রকাশ্যে পৌঁছানোযোগ্য URL-এ HTTPS ব্যবহার করুন; Telm অভ্যন্তরীণ ও প্রাইভেট ঠিকানা ব্লক করে এবং রিডাইরেক্ট অনুসরণ করে না।
• whsec_ সিক্রেটটি লগ ও ক্লায়েন্ট কোডের বাইরে রাখুন।