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

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

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

ওয়েবহুক কী?

একটি ওয়েবহুক হল একটি HTTP কলব্যাক: একটি নির্দিষ্ট ইভেন্ট ঘটলে একটি সিস্টেম আপনার দেওয়া URL-এ একটি HTTP POST অনুরোধ পাঠায়। পোলিংয়ের বিপরীতে, যেখানে আপনি বারবার জিজ্ঞাসা করেন "কিছু ঘটেছে কি?", ওয়েবহুক প্রায় রিয়েল-টাইমে ইভেন্টগুলি আপনার কাছে পুশ করে।

সাধারণ ব্যবহারের মধ্যে রয়েছে:

• পেমেন্ট প্রসেসরগুলি আপনাকে সফল চার্জ সম্পর্কে অবহিত করে।
• Git হোস্টিং পরিষেবাগুলি পুশে CI/CD পাইপলাইন ট্রিগার করে।
• যোগাযোগ প্ল্যাটফর্মগুলি নতুন বার্তা সম্পর্কে আপনাকে সতর্ক করে।

প্রেরক (যেমন, Stripe, GitHub) হল ওয়েবহুক প্রদানকারী; আপনার সার্ভার হল ওয়েবহুক গ্রাহক।

কেন স্বাক্ষরিত পেলোড অপরিহার্য

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

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

এইচএমএসি স্বাক্ষর কীভাবে কাজ করে

বেশিরভাগ প্রদানকারী HMAC-SHA256 ব্যবহার করে। প্রদানকারী গণনা করে:

signature = HMAC-SHA256(secret, payload)

এবং এটি X-Signature এর মতো একটি হেডারে পাঠায়। আপনার সার্ভার একই গণনা করে এবং সমতা পরীক্ষা করে। যেহেতু সিক্রেটটি গোপন, শুধুমাত্র প্রদানকারী একটি বৈধ স্বাক্ষর তৈরি করতে পারে।

বাস্তবে একটি স্বাক্ষর যাচাই করা

এখানে Express ব্যবহার করে একটি ন্যূনতম Node.js উদাহরণ:

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  const payload = req.body; // raw Buffer

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const event = JSON.parse(payload);
  console.log('Received event:', event.type);
  res.status(200).send('OK');
});

app.listen(3000);

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

সাধারণ ভুলগুলি

• ভুল সিক্রেট ব্যবহার: কিছু প্রদানকারীর টেস্ট এবং লাইভ মোডের জন্য আলাদা সিক্রেট থাকে।
• টাইমিং আক্রমণ: তথ্য ফাঁস এড়াতে একটি ধ্রুবক-সময়ের তুলনা ফাংশন (যেমন, crypto.timingSafeEqual) ব্যবহার করুন।
• টাইমস্ট্যাম্প হেডার উপেক্ষা করা: অনেক প্রদানকারী রিপ্লে আক্রমণ প্রতিরোধের জন্য একটি টাইমস্ট্যাম্প অন্তর্ভুক্ত করে। কয়েক মিনিটের চেয়ে পুরানো অনুরোধ প্রত্যাখ্যান করুন।

পুনঃপ্রচেষ্টা: ব্যর্থতা সুন্দরভাবে সামলানো

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

প্রদানকারীরা কীভাবে পুনঃপ্রচেষ্টা করে

বেশিরভাগ প্রদানকারী সূচকীয় ব্যাকঅফ ব্যবহার করে: তারা প্রথম ব্যর্থতার পরে অল্প সময় অপেক্ষা করে, তারপর ক্রমবর্ধমান দীর্ঘ বিরতি। উদাহরণস্বরূপ, Stripe ক্রমবর্ধমান বিলম্বের সাথে 3 দিন পর্যন্ত পুনঃপ্রচেষ্টা করে। GitHub 8 বার পর্যন্ত পুনঃপ্রচেষ্টা করে। সঠিক সময়সূচি পরিবর্তিত হয়, কিন্তু প্যাটার্নটি সামঞ্জস্যপূর্ণ।

আপনার এন্ডপয়েন্টের প্রাপ্তি স্বীকার করতে দ্রুত একটি 2xx স্ট্যাটাস কোড ফেরত দেওয়া উচিত। অন্য যেকোনো স্ট্যাটাস (4xx, 5xx) ব্যর্থতার সংকেত দেয় এবং একটি পুনঃপ্রচেষ্টা ট্রিগার করে।

আইডেম্পোটেন্ট হ্যান্ডলার তৈরি করা

যেহেতু পুনঃপ্রচেষ্টা একই ইভেন্ট একাধিকবার সরবরাহ করতে পারে, আপনার হ্যান্ডলারকে আইডেম্পোটেন্ট হতে হবে: একই ইভেন্ট দুবার প্রক্রিয়া করা একবার প্রক্রিয়া করার মতোই প্রভাব ফেলবে।

সাধারণ কৌশল:

• ইভেন্ট আইডি ট্র্যাকিং: পেলোড বা হেডারে প্রদত্ত অনন্য ইভেন্ট আইডি একটি ডেটাবেসে সংরক্ষণ করুন। প্রক্রিয়া করার আগে, এটি ইতিমধ্যে পরিচালিত হয়েছে কিনা তা পরীক্ষা করুন।
• আপসার্ট: ডেটাবেস অপারেশন ব্যবহার করুন যা স্বাভাবিকভাবেই আইডেম্পোটেন্ট (যেমন, INSERT ... ON CONFLICT DO NOTHING)।
• স্টেট মেশিন: আপনার ব্যবসায়িক লজিক ডিজাইন করুন যাতে পুনরাবৃত্ত ট্রানজিশন সহ্য করে (যেমন, "অর্ডারটি পরিশোধিত হিসাবে চিহ্নিত করুন" শুধুমাত্র যদি ইতিমধ্যে পরিশোধিত না হয়)।

একটি সাধারণ ইন-মেমরি সেট ব্যবহার করে উদাহরণ (চিত্রের জন্য; প্রোডাকশনে একটি স্থায়ী স্টোর ব্যবহার করুন):

const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const event = req.body;
  if (processedEvents.has(event.id)) {
    return res.status(200).send('Already processed');
  }
  // Process event...
  processedEvents.add(event.id);
  res.status(200).send('OK');
});

দ্রুত প্রতিক্রিয়া জানানো

প্রদানকারীদের প্রায়শই একটি টাইমআউট থাকে (যেমন, 5 সেকেন্ড)। যদি আপনার হ্যান্ডলার ভারী প্রক্রিয়াকরণ করে, অবিলম্বে স্বীকার করুন এবং অ্যাসিঙ্ক্রোনাসভাবে প্রক্রিয়া করুন। উদাহরণস্বরূপ, ইভেন্টটি একটি কিউতে পুশ করুন এবং 200 ফেরত দিন।

নির্ভরযোগ্য ওয়েবহুকের জন্য সর্বোত্তম অনুশীলন

1. সর্বদা স্বাক্ষর যাচাই করুন কাঁচা বডি এবং একটি ধ্রুবক-সময়ের তুলনা ব্যবহার করে।
2. HTTPS ব্যবহার করুন ইভসড্রপিং এবং টেম্পারিং প্রতিরোধ করতে আপনার এন্ডপয়েন্টের জন্য।
3. আইডেম্পোটেন্সি প্রয়োগ করুন ডুপ্লিকেট ডেলিভারি সামলাতে।
4. সবকিছু লগ করুন — আগত পেলোড, স্বাক্ষর, এবং আপনার প্রতিক্রিয়া — ডিবাগিংয়ের জন্য।
5. ব্যর্থতা মনিটর করুন এবং পুনরাবৃত্ত ত্রুটির জন্য সতর্কতা সেট আপ করুন।
6. প্রদানকারী ড্যাশবোর্ড বা CLI টুল ব্যবহার করে বাস্তব ইভেন্টের সাথে পরীক্ষা করুন।
7. ক্রমবহির্ভূত ইভেন্ট পরিচালনা করুন আপনার লজিকে টাইমস্ট্যাম্প বা সিকোয়েন্স নম্বর অন্তর্ভুক্ত করে।

তুলনা: পোলিং বনাম ওয়েবহুক

সাধারণ প্রশ্ন

ওয়েবহুক স্বাক্ষর কী?

একটি ওয়েবহুক স্বাক্ষর হল পেলোডের একটি ক্রিপ্টোগ্রাফিক হ্যাশ (সাধারণত HMAC-SHA256), একটি শেয়ার্ড সিক্রেট দিয়ে তৈরি। এটি প্রাপককে যাচাই করতে দেয় যে অনুরোধটি প্রত্যাশিত প্রেরকের কাছ থেকে এসেছে এবং টেম্পার করা হয়নি।

আমি কীভাবে ডুপ্লিকেট ওয়েবহুক ইভেন্ট পরিচালনা করব?

ইভেন্ট আইডি ট্র্যাক করে বা স্বাভাবিকভাবেই আইডেম্পোটেন্ট ডেটাবেস অপারেশন ব্যবহার করে আপনার হ্যান্ডলারকে আইডেম্পোটেন্ট করুন। পরিবর্তন প্রয়োগ করার আগে একটি ইভেন্ট ইতিমধ্যে প্রক্রিয়া করা হয়েছে কিনা তা পরীক্ষা করুন।

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

আপনি ইভেন্টটি পেয়ে এবং যাচাই করার সাথে সাথে একটি 2xx স্ট্যাটাস কোড (যেমন, 200 OK) ফেরত দিন। যদি আপনার ভারী প্রক্রিয়াকরণ করতে হয়, অবিলম্বে স্বীকার করুন এবং অ্যাসিঙ্ক্রোনাসভাবে কাজটি পরিচালনা করুন।

আপনার ওয়েবহুক পেলোড পরীক্ষা করতে প্রস্তুত? আগত ইভেন্টের JSON কাঠামো পরিদর্শন এবং যাচাই করতে আমাদের JSON Formatter ব্যবহার করুন।