ওয়েবহুক ব্যাখ্যা: সাইনড পেলোড এবং রিট্রাই

আপনি সবেমাত্র একটি থার্ড-পার্টি পেমেন্ট প্রোভাইডার ইন্টিগ্রেট করেছেন। ডকুমেন্টেশনে বলা হয়েছে: "পেমেন্ট সফল হলে আমরা একটি ওয়েবহুক পাঠাব।" সহজ, তাই না? কিন্তু তারপর আপনি বুঝতে পারেন: কীভাবে জানবেন যে রিকোয়েস্টটি সত্যিই তাদের কাছ থেকে এসেছে? যদি তারা পাঠানোর সময় আপনার সার্ভার ডাউন থাকে? যদি তারা একই ইভেন্ট দুবার পাঠায়?

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

ওয়েবহুক কী?

একটি ওয়েবহুক হলো একটি HTTP কলব্যাক: আপনার অ্যাপ পরিবর্তনের জন্য একটি API পোলিং করার পরিবর্তে, প্রোভাইডার একটি ইভেন্ট ঘটলে আপনার নির্দিষ্ট করা URL-এ একটি HTTP POST পাঠায়। এটি ইন্টিগ্রেশনকে দক্ষ এবং প্রায় রিয়েল-টাইম করে তোলে।

সাধারণ উদাহরণগুলির মধ্যে রয়েছে পেমেন্ট নোটিফিকেশন (Stripe, PayPal), CI/CD ট্রিগার (GitHub, GitLab), এবং মেসেজিং প্ল্যাটফর্ম (Slack, Discord)।

কেন সিগনেচার দিয়ে ওয়েবহুক সুরক্ষিত করবেন?

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

একটি শেয়ার্ড সিক্রেট দিয়ে পেলোড সাইন করা আপনাকে যাচাই করতে দেয় যে রিকোয়েস্টটি প্রত্যাশিত প্রেরকের কাছ থেকে এসেছে এবং পেলোডের সাথে ছेড়াছড়ি করা হয়নি।

HMAC সিগনেচার কীভাবে কাজ করে

প্রোভাইডার এবং আপনি একটি সিক্রেট কী শেয়ার করেন। প্রতিটি ওয়েবহুকের জন্য, প্রোভাইডার সেই সিক্রেট ব্যবহার করে পেলোডের একটি HMAC (হ্যাশ-ভিত্তিক মেসেজ অথেনটিকেশন কোড) গণনা করে এবং একটি হেডারে সিগনেচার অন্তর্ভুক্ত করে (যেমন, X-Signature)। আপনি আপনার দিকে HMAC পুনরায় গণনা করেন এবং তুলনা করেন।

HMAC অখণ্ডতা এবং প্রামাণিকতা নিশ্চিত করে কারণ শুধুমাত্র যার সিক্রেট আছে সে একটি বৈধ সিগনেচার তৈরি করতে পারে।

সাইনড পেলোড বাস্তবায়ন

চলুন Node.js (Express) এবং Python (Flask)-এ একটি সাধারণ বাস্তবায়ন দেখি। নীতিগুলি যেকোনো ভাষায় প্রযোজ্য।

ধাপ ১: সিক্রেট সংগ্রহ ও সংরক্ষণ

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

ধাপ ২: কাঁচা বডি ক্যাপচার

সিগনেচার যাচাইয়ের জন্য সঠিক কাঁচা বডি বাইট প্রয়োজন। যদি আপনার ফ্রেমওয়ার্ক যাচাই করার আগে JSON পার্স করে, পুনরায় সিরিয়ালাইজ করা বাইট পরিবর্তন করতে পারে এবং যাচাই ব্যর্থ হতে পারে।

Express-এ, ওয়েবহুক রুটের জন্য express.raw({ type: 'application/json' }) ব্যবহার করুন। Flask-এ, পার্স করার আগে request.get_data() অ্যাক্সেস করুন।

ধাপ ৩: সিগনেচার গণনা ও তুলনা

টাইমিং আক্রমণ প্রতিরোধ করতে একটি ধ্রুবক-সময় তুলনা ফাংশন ব্যবহার করুন।

// Node.js (Express)
const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  const event = JSON.parse(req.body);
  // ... handle event
  res.status(200).send('OK');
});

Python-এ, hmac.compare_digest ব্যবহার করুন:

# Python (Flask)
import hmac, hashlib, os
from flask import request, abort

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    secret = os.environ['WEBHOOK_SECRET'].encode()
    expected = hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    event = request.get_json()
    # ... handle event
    return 'OK', 200

ধাপ ৪: টাইমস্ট্যাম্প হ্যান্ডেল (ঐচ্ছিক কিন্তু সুপারিশকৃত)

কিছু প্রোভাইডার রিপ্লে আক্রমণ প্রতিরোধ করতে সিগনেচারে একটি টাইমস্ট্যাম্প অন্তর্ভুক্ত করে। উদাহরণস্বরূপ, Stripe-এর স্কিম timestamp.payload সাইন করে। আপনার উচিত অতীতে খুব পুরনো টাইমস্ট্যাম্প (যেমন, ৫ মিনিটের বেশি পুরনো) সহ রিকোয়েস্ট প্রত্যাখ্যান করা।

রিট্রাই বাস্তবায়ন

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

প্রোভাইডার পক্ষে

যদি আপনি ওয়েবহুক প্রেরক তৈরি করেন, এক্সপোনেনশিয়াল ব্যাকঅফ সহ রিট্রাই বাস্তবায়ন করুন। একটি সাধারণ প্যাটার্ন: ১ মিনিট পরে, তারপর ৫ মিনিট, তারপর ৩০ মিনিট, ইত্যাদি, সর্বোচ্চ সংখ্যক চেষ্টা পর্যন্ত (যেমন, ৫)। পেলোডে একটি অনন্য ইভেন্ট আইডি অন্তর্ভুক্ত করুন যাতে প্রাপক ডুপ্লিকেট করতে পারে।

প্রাপক পক্ষে

একজন প্রাপক হিসেবে, আপনার উচিত:

• দ্রুত (কয়েক সেকেন্ডের মধ্যে) 2xx স্ট্যাটাস দিয়ে সাড়া দেওয়া। ভারী প্রসেসিং অ্যাসিনক্রোনাসভাবে করুন।
• যে ত্রুটিগুলি রিট্রাই প্রয়োজন (যেমন, 500) সেগুলির জন্য non-2xx ফেরত দিন। তবে সতর্ক থাকুন: যদি আপনি 4xx ফেরত দেন, প্রোভাইডার রিট্রাই নাও করতে পারে।
• আপনার এন্ডপয়েন্ট আইডেম্পোটেন্ট করুন যাতে ডুপ্লিকেট ডেলিভারি সমস্যা না করে।

আইডেম্পোটেন্সি: ডুপ্লিকেট ইভেন্ট হ্যান্ডলিং

রিট্রাই ডুপ্লিকেট ইভেন্টের দিকে নিয়ে যেতে পারে। প্রসেস করা ইভেন্ট ট্র্যাক করতে ইভেন্ট আইডি (বেশিরভাগ প্রোভাইডার দ্বারা অন্তর্ভুক্ত) ব্যবহার করুন। প্রসেস করার আগে, আইডি আগে দেখা হয়েছে কিনা পরীক্ষা করুন; যদি তাই হয়, এড়িয়ে যান।

TTL সহ একটি ডাটাবেসে প্রসেস করা আইডি সংরক্ষণ করুন, অথবা আপনার ব্যবসায়িক লজিকে একটি আইডেম্পোটেন্সি কী ব্যবহার করুন।

স্থানীয়ভাবে ওয়েবহুক পরীক্ষা

বিকাশের সময়, আপনার স্থানীয় সার্ভার সর্বজনীনভাবে অ্যাক্সেসযোগ্য নয়। ngrok বা localtunnel-এর মতো টুল একটি সর্বজনীন URL তৈরি করে যা আপনার মেশিনে টানেল করে। বিকল্পভাবে, একটি ওয়েবহুক টেস্টিং সেবা ব্যবহার করুন যা রিকোয়েস্ট ক্যাপচার করে এবং আপনাকে সেগুলি রিপ্লে করতে দেয়।

সাধারণ ভুল এবং সেরা অনুশীলন

• যাচাইয়ের আগে পেলোডে বিশ্বাস করবেন না। সর্বদা প্রথমে সিগনেচার যাচাই করুন।
• HTTPS ব্যবহার করুন। ওয়েবহুক সংবেদনশীল ডেটা বহন করে; ট্রানজিটে এনক্রিপ্ট করুন।
• সবকিছু লগ করুন। ডিবাগিংয়ের জন্য কাঁচা রিকোয়েস্ট (হেডার এবং বডি) লগ করুন, কিন্তু সংবেদনশীল তথ্য লুকান।
• ব্যর্থতা মনিটর করুন। বারবার ওয়েবহুক ব্যর্থতার জন্য সতর্কতা সেট আপ করুন।
• আপনার ইভেন্ট সংস্করণ করুন। পেলোডে একটি সংস্করণ অন্তর্ভুক্ত করুন যাতে প্রাপকদের ভাঙা ছাড়াই আপনি বিবর্তিত হতে পারেন।

তুলনা: সাইনড বনাম আনসাইনড ওয়েবহুক

সাধারণ জিজ্ঞাসা

কীভাবে একটি ওয়েবহুক সিগনেচার যাচাই করব?

শেয়ার্ড সিক্রেট ব্যবহার করে কাঁচা রিকোয়েস্ট বডির একটি HMAC গণনা করুন, তারপর একটি ধ্রুবক-সময় ফাংশন ব্যবহার করে সিগনেচার হেডারের সাথে তুলনা করুন। সর্বদা কাঁচা বডি ব্যবহার করুন, পার্স করা JSON নয়।

আমার ওয়েবহুক এন্ডপয়েন্ট কী ফেরত দেওয়া উচিত?

প্রাপ্তি স্বীকার করতে দ্রুত একটি 2xx স্ট্যাটাস কোড ফেরত দিন। যদি প্রসেসিং ব্যর্থ হয়, রিট্রাই ট্রিগার করতে 5xx ফেরত দিন, তবে ডুপ্লিকেট হ্যান্ডল করতে আপনার এন্ডপয়েন্ট আইডেম্পোটেন্ট কিনা নিশ্চিত করুন।

একটি ওয়েবহুক কতবার রিট্রাই হবে?

এটি প্রোভাইডারের উপর নির্ভর করে। বেশিরভাগ কয়েক ঘন্টা বা দিনের মধ্যে এক্সপোনেনশিয়াল ব্যাকঅফ সহ কয়েকবার রিট্রাই করে। নির্দিষ্ট তথ্যের জন্য প্রোভাইডারের ডকুমেন্টেশন দেখুন।

ওয়েবহুক ডেলিভারি ডিবাগ করার সময়, সার্ভার লগ পরিদর্শন প্রায়শই প্রয়োজনীয়। যদি আপনি Nginx ব্যবহার করেন, Nginx Log Analyzer আপনাকে ব্যর্থ রিকোয়েস্ট বা অস্বাভাবিক প্যাটার্ন স্পট করতে অ্যাক্সেস লগ পার্স এবং বিশ্লেষণ করতে সাহায্য করতে পারে।