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

Backend2026-11-11TryQuickToolBox

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

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

ওয়েবহুক আসলে কী

ওয়েবহুক হলো একটি রিভার্স API কল। আপনার সার্ভার প্রতি মিনিটে প্রোভাইডারকে জিজ্ঞাসা করে "নতুন কিছু আছে?" — এই পোলিংয়ের বদলে, প্রোভাইডার একটি ইভেন্ট ঘটলে আপনার নিবন্ধিত URL-এ একটি HTTP রিকোয়েস্ট পুশ করে। পেলোড সাধারণত JSON হয়, এবং ইভেন্টের ধরন হয় বডিতে অথবা হেডারে থাকে।

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

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

আনসাইনড ওয়েবহুক কেন বিপজ্জনক

আপনার ওয়েবহুক URL পাবলিক। যে কেউ এটি জানতে পারলে একটি ভুয়া payment.succeeded ইভেন্ট POST করে একটি অপরিশোধিত অর্ডারকে পরিশোধিত হিসেবে চিহ্নিত করতে পারে। একটি IP অ্যালাউলিস্ট কিছুটা সাহায্য করে, কিন্তু প্রোভাইডাররা IP পরিবর্তন করে, CDN-এর পিছনে চলে, এবং আপনি হয়তো একটি স্থিতিশীল তালিকা পাবেন না।

শক্তিশালী সমাধান হলো একটি শেয়ার্ড সিক্রেট ব্যবহার করে র' রিকোয়েস্ট বডির উপর HMAC সিগনেচার, যা শুধু আপনি এবং প্রোভাইডার জানেন। প্রোভাইডার সিগনেচার গণনা করে একটি হেডারে পাঠায়; আপনি এটি পুনরায় গণনা করে তুলনা করেন।

সঠিকভাবে সিগনেচার যাচাই করা

তিনটি বিশদ ভুল করা সহজ:

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

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Reject stale requests (replay protection)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... handle event
  res.status(200).send('ok');
});

express.raw() মিডলওয়্যারটি লক্ষ্য করুন। যদি আপনি এই রুটের আগে express.json() মাউন্ট করেন, তাহলে বডি ইতিমধ্যে পার্স হয়ে যায় এবং সিগনেচার চেক নীরবে ব্যর্থ হয় — এটি একটি খুব সাধারণ বাগ।

রিট্রাই ডিজাইন করা যা ইভেন্ট হারায় না

ওয়েবহুক ডেলিভারি at-least-once, exactly-once নয়। নেটওয়ার্ক ব্যর্থ হয়, আপনার ডিপ্লয় একটি কন্টেইনার রিস্টার্ট করে, এবং প্রোভাইডারের কোনো ধারণা নেই আপনার 200 রেসপন্স আসল ছিল কিনা। তাই প্রোভাইডার এক্সপোনেনশিয়াল ব্যাকঅফের সাথে রিট্রাই করে, প্রায়শই ঘন্টা বা দিনের জন্য।

দ্রুত রেসপন্স দিন, পরে প্রসেস করুন

আপনার এন্ডপয়েন্টের ন্যূনতম কাজ করা উচিত: যাচাই করা, র' ইভেন্ট সংরক্ষণ করা, 2xx ফেরত দেওয়া। ভারী কাজ — ইমেইল পাঠানো, অন্য API কল করা, ইনভয়েস তৈরি করা — ব্যাকগ্রাউন্ড জবে হওয়া উচিত। যদি প্রসেসিং প্রোভাইডারের টাইমআউটের চেয়ে বেশি সময় নেয়, তাহলে রিকোয়েস্টটি ব্যর্থ হিসেবে বিবেচিত হয় এবং রিট্রাই হয় যদিও আপনি কাজটি সম্পন্ন করেছেন।

  1. সিগনেচার এবং টাইমস্ট্যাম্প যাচাই করুন।
  2. ইভেন্ট আইডিতে ইউনিক কনস্ট্রেইন্ট সহ একটি টেবিলে ইভেন্টটি সন্নিবেশ করুন।
  3. সাথে সাথে 200 ফেরত দিন।
  4. সংরক্ষিত ইভেন্টটি অ্যাসিনক্রোনাসভাবে প্রসেস করুন, এটি সম্পন্ন হিসেবে চিহ্নিত করুন।

আইডেম্পোটেন্সি: ডুপ্লিকেটের আসল সমাধান

যেহেতু রিট্রাই ঘটে, তাই আপনার হ্যান্ডলারকে দুইবার চালানো নিরাপদ হতে হবে। ইভেন্ট আইডি হলো স্বাভাবিক আইডেম্পোটেন্সি কী।

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

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

সচেতনভাবে স্ট্যাটাস কোড নির্বাচন করা

স্ট্যাটাসপ্রোভাইডারের আচরণকখন ব্যবহার করবেন
200 / 204ডেলিভার্ড হিসেবে চিহ্নিত করেইভেন্ট গ্রহণ করা হয়েছে (এমনকি যদি ইতিমধ্যে প্রসেস করা হয়ে থাকে)
400সাধারণত রিট্রাই করে নাত্রুটিপূর্ণ পেলোড যা আপনি কখনও হ্যান্ডল করতে পারবেন না
401সাধারণত রিট্রাই করে নাসিগনেচার মিসম্যাচ — আপনার সিক্রেট পরীক্ষা করুন
429ব্যাকঅফের সাথে রিট্রাইআপনি রেট লিমিট করছেন
500 / 503ব্যাকঅফের সাথে রিট্রাইসাময়িক ব্যর্থতা, DB ডাউন, ডিপ্লয় চলছে

এমন একটি ইভেন্টের জন্য 200 ফেরত দেওয়া যা আপনি সংরক্ষণ করতে পারেননি সবচেয়ে খারাপ বিকল্প: প্রোভাইডার রিট্রাই বন্ধ করে দেয় এবং ইভেন্টটি চিরতরে হারিয়ে যায়। একটি 5xx ফেরত দিন এবং রিট্রাইকে তার কাজ করতে দিন।

প্রোডাকশনের জন্য ব্যবহারিক চেকলিস্ট

লোকালি ওয়েবহুক টেস্ট করা

আপনি localhost-এ সহজে একটি পাবলিক POST পেতে পারেন না। বিকল্প: একটি টানেলিং টুল যা আপনার ডেভ পোর্ট এক্সপোজ করে, প্রোভাইডারের CLI যদি থাকে, অথবা একটি ছোট স্ক্রিপ্ট যা আপনার হ্যান্ডলারে একটি সাইনড পেলোড পাঠায় যাতে আপনি যাচাইয়ের পথটি পরীক্ষা করতে পারেন।

সবচেয়ে মূল্যবান পরীক্ষা হলো ডুপ্লিকেট: একই ইভেন্ট দুবার পাঠান এবং নিশ্চিত করুন যে আপনার সিস্টেম একই অবস্থায় শেষ হয়। তারপর একটি পুরনো টাইমস্ট্যাম্প সহ একটি ইভেন্ট পাঠান এবং নিশ্চিত করুন যে এটি প্রত্যাখ্যাত হয়। তারপর বডির এক বাইট পরিবর্তন করুন এবং নিশ্চিত করুন যে সিগনেচার চেক ব্যর্থ হয়।

পেলোড ডিবাগিং

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

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

ওয়েবহুক এবং API-এর মধ্যে পার্থক্য কী?

একটি API পুল-ভিত্তিক: আপনার কোড যখন ডেটা প্রয়োজন তখন প্রোভাইডারকে কল করে। একটি ওয়েবহুক পুশ-ভিত্তিক: একটি ইভেন্ট ঘটলে প্রোভাইডার আপনার এন্ডপয়েন্টকে কল করে। বেশিরভাগ ইন্টিগ্রেশন উভয়ই ব্যবহার করে — ইভেন্ট নোটিফিকেশনের জন্য ওয়েবহুক এবং সম্পূর্ণ বিবরণ আনতে বা কাজ সম্পাদনের জন্য API।

কেন আমার HMAC সিগনেচার কখনও মেলে না?

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

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

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

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