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

আপনি সবেমাত্র একটি পেমেন্ট গেটওয়ে ইন্টিগ্রেট করেছেন। ডকুমেন্টেশনে বলা আছে: "পেমেন্ট সফল হলে আমরা আপনার এন্ডপয়েন্টে একটি POST রিকোয়েস্ট পাঠাব।" সহজ, তাই না? আপনি একটি সাধারণ রুট তৈরি করেন যা JSON গ্রহণ করে, আপনার ডেটাবেস আপডেট করে এবং 200 রিটার্ন করে। তারপর ঘটে যায়: একজন গ্রাহকের পেমেন্ট সফল হয়, কিন্তু আপনার সার্ভার সাময়িকভাবে ডাউন থাকে। ওয়েবহুক কখনো পৌঁছায় না। বা আরও খারাপ, এটি দুবার পৌঁছায়, এবং আপনি অ্যাকাউন্টে দ্বিগুণ ক্রেডিট দেন। ওয়েবহুক সহজ মনে হয় যতক্ষণ না এটি ব্যর্থ হয়।

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

ওয়েবহুক কী?

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

সাধারণ উদাহরণগুলির মধ্যে রয়েছে পেমেন্ট নিশ্চিতকরণ (Stripe, PayPal), CI/CD বিল্ড নোটিফিকেশন (GitHub, GitLab), এবং মেসেজিং প্ল্যাটফর্ম (Slack, Discord)। প্যাটার্নটি সহজ: আপনি একটি URL নিবন্ধন করেন, প্রদানকারী সেই URL-এ JSON পেলোড পাঠায়, এবং আপনার সার্ভার সেগুলি প্রক্রিয়া করে।

কিন্তু এই সরলতা দুটি গুরুত্বপূর্ণ চ্যালেঞ্জ লুকিয়ে রাখে: প্রামাণিকতা (আপনি কীভাবে জানবেন যে রিকোয়েস্টটি সত্যিই প্রদানকারীর কাছ থেকে এসেছে?) এবং নির্ভরযোগ্যতা (আপনার এন্ডপয়েন্ট ডাউন বা ধীর হলে কী হবে?)।

সাইনড পেলোড কেন গুরুত্বপূর্ণ

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

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

HMAC সাইনিং কীভাবে কাজ করে

1. প্রদানকারী এবং আপনি একটি শেয়ার্ড সিক্রেট কী শেয়ার করেন (সেটআপের সময় প্রদত্ত)।
2. প্রতিটি ওয়েবহুকের জন্য, প্রদানকারী টাইমস্ট্যাম্প এবং কাঁচা রিকোয়েস্ট বডি সংযুক্ত করে, তারপর সিক্রেট ব্যবহার করে একটি HMAC-SHA256 হ্যাশ গণনা করে।
3. সিগনেচারটি একটি হেডারে পাঠানো হয়, প্রায়শই X-Signature বা Stripe-Signature এর মতো কিছু।
4. আপনার সার্ভার একই সিক্রেট ব্যবহার করে HMAC পুনরায় গণনা করে এবং প্রাপ্ত সিগনেচারের সাথে তুলনা করে।
5. যদি তারা মেলে, আপনি ইভেন্টটি প্রক্রিয়া করেন; অন্যথায়, আপনি 401 দিয়ে এটি প্রত্যাখ্যান করেন।

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

উদাহরণ: Node.js-এ ওয়েবহুক সিগনেচার যাচাই করা

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

// Use raw body for signature verification
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; // Buffer

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

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const event = JSON.parse(payload.toString());
  // ... handle event

  res.status(200).send('OK');
});

টাইমিং অ্যাটাক প্রতিরোধে timingSafeEqual এর ব্যবহার লক্ষ্য করুন। সিগনেচারের জন্য কখনোই সাধারণ === তুলনা ব্যবহার করবেন না।

রিট্রাই লজিক ডিজাইন করা

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

কী ব্যর্থতা হিসেবে গণ্য হয়?

বেশিরভাগ প্রদানকারী 2xx ব্যতীত যেকোনো প্রতিক্রিয়াকে ব্যর্থতা হিসেবে বিবেচনা করে। এর মধ্যে 3xx রিডাইরেক্ট, 4xx ক্লায়েন্ট ত্রুটি, এবং 5xx সার্ভার ত্রুটি অন্তর্ভুক্ত। কিছু একটি টাইমআউটও প্রয়োগ করে (যেমন, 5 সেকেন্ড)। যদি আপনি দ্রুত প্রতিক্রিয়া না দেন, ডেলিভারি ব্যর্থ হিসেবে চিহ্নিত হয় এবং রিট্রাই করা হয়।

জিটার সহ এক্সপোনেনশিয়াল ব্যাকঅফ

প্রদানকারীরা সাধারণত এক্সপোনেনশিয়াল ব্যাকঅফ সহ রিট্রাই করে: প্রথম রিট্রাই 1 মিনিট পরে, তারপর 5 মিনিট, 30 মিনিট, ইত্যাদি। জিটার (এলোমেলো ভিন্নতা) যোগ করা থান্ডারিং হার্ড প্রতিরোধ করে যদি একসাথে অনেক ওয়েবহুক ব্যর্থ হয়।

যদি আপনি একটি ওয়েবহুক সেন্ডার তৈরি করেন, এইভাবে ব্যাকঅফ প্রয়োগ করুন:

• রিট্রাই 1: 10 সেকেন্ড পরে
• রিট্রাই 2: 1 মিনিট পরে
• রিট্রাই 3: 5 মিনিট পরে
• রিট্রাই 4: 30 মিনিট পরে
• রিট্রাই 5: 2 ঘন্টা পরে

সর্বাধিক সংখ্যক প্রচেষ্টার পরে, ম্যানুয়াল পরিদর্শনের জন্য ইভেন্টটি একটি ডেড-লেটার কিউতে সরান।

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

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

সাধারণ কৌশল:

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

ওয়েবহুক কনজিউমারদের জন্য সেরা অনুশীলন

এছাড়াও রিপ্লে অ্যাটাক প্রতিরোধে সিগনেচারে টাইমস্ট্যাম্প যাচাই করার কথা বিবেচনা করুন। অনেক প্রদানকারী সাইনড পেলোডে একটি টাইমস্ট্যাম্প অন্তর্ভুক্ত করে; কয়েক মিনিটের চেয়ে পুরানো ইভেন্ট প্রত্যাখ্যান করুন।

ওয়েবহুক প্রোডিউসারদের জন্য সেরা অনুশীলন

যদি আপনি একটি পরিষেবা তৈরি করেন যা ওয়েবহুক পাঠায়, এই নির্দেশিকাগুলি অনুসরণ করুন:

• প্রতিটি পেলোড HMAC-SHA256 দিয়ে সাইন করুন।
• একটি অনন্য ইভেন্ট আইডি এবং টাইমস্ট্যাম্প অন্তর্ভুক্ত করুন।
• এক্সপোনেনশিয়াল ব্যাকঅফ এবং জিটার সহ রিট্রাই করুন।
• কনজিউমারদের ডেলিভারি লগ দেখতে এবং ম্যানুয়ালি ইভেন্ট রিপ্লে করার একটি উপায় প্রদান করুন।
• আপনার সিগনেচার যাচাইকরণ প্রক্রিয়া স্পষ্টভাবে ডকুমেন্ট করুন।

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

একটি সাইনড ওয়েবহুক পেলোড কী?

একটি সাইনড পেলোডে একটি ক্রিপ্টোগ্রাফিক সিগনেচার (সাধারণত HMAC) থাকে যা রিকোয়েস্ট বডি এবং একটি শেয়ার্ড সিক্রেট থেকে গণনা করা হয়। রিসিভার সিগনেচার যাচাই করে নিশ্চিত করে যে রিকোয়েস্টটি প্রামাণিক এবং অপরিবর্তিত।

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

কোন সার্বজনীন সংখ্যা নেই, তবে বেশিরভাগ প্রদানকারী কয়েক ঘন্টার মধ্যে 3–5 বার রিট্রাই করে। এর পরে, ইভেন্টটি সাধারণত ব্যর্থ হিসেবে চিহ্নিত হয় এবং ম্যানুয়াল রিপ্লের জন্য উপলব্ধ থাকতে পারে। আপনার সিস্টেম রিট্রাই সংখ্যা নির্বিশেষে ডুপ্লিকেট আইডেম্পোটেন্টভাবে হ্যান্ডল করা উচিত।

আমি HTTPS ছাড়া ওয়েবহুক ব্যবহার করতে পারি?

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

Nginx লগ দিয়ে ওয়েবহুক ডিবাগিং

যখন ওয়েবহুক ব্যর্থ হয়, প্রথমে দেখার জায়গা হল আপনার ওয়েব সার্ভার লগ। যদি আপনি Nginx ব্যবহার করেন, অ্যাক্সেস এবং এরর লগ প্রতিটি রিকোয়েস্ট রেকর্ড করে, স্ট্যাটাস কোড এবং প্রতিক্রিয়া সময় সহ। আপনি দ্রুত প্যাটার্ন স্পট করতে পারেন: বারবার 401s (সিগনেচার যাচাইকরণ ব্যর্থ), 500s (অ্যাপ্লিকেশন ত্রুটি), বা টাইমআউট।

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