ওয়েবহুকস ব্যাখ্যা: সাইনড পেলোড এবং নির্ভরযোগ্য রিট্রাই
আপনি একটি পেমেন্ট ইন্টিগ্রেশন তৈরি করেছেন এবং স্টেজিং-এ সবকিছু ঠিকঠাক কাজ করছে। তারপর প্রোডাকশনে একজন গ্রাহক পেমেন্ট করলেন, আপনার এন্ডপয়েন্ট দুই সেকেন্ডের জন্য টাইমআউট হলো, এবং অর্ডারটি কখনও সক্রিয় হলো না। এদিকে পেমেন্ট প্রোভাইডার একই ইভেন্ট তিনবার রিট্রাই করছে, এবং আপনার অ্যাপ সফল হওয়া ইভেন্টটির জন্য তিনটি ডুপ্লিকেট অর্ডার তৈরি করছে। ওয়েবহুক দেখতে সহজ — শুধু একটি 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 সিগনেচার, যা শুধু আপনি এবং প্রোভাইডার জানেন। প্রোভাইডার সিগনেচার গণনা করে একটি হেডারে পাঠায়; আপনি এটি পুনরায় গণনা করে তুলনা করেন।
সঠিকভাবে সিগনেচার যাচাই করা
তিনটি বিশদ ভুল করা সহজ:
- র' বডি ব্যবহার করুন। যাচাইয়ের পরেই JSON পার্স করুন। একটি পার্স করা অবজেক্ট পুনরায় সিরিয়ালাইজ করলে হোয়াইটস্পেস এবং কী-এর ক্রম পরিবর্তিত হয়, তাই সিগনেচার কখনও মিলবে না।
- কনস্ট্যান্ট টাইমে তুলনা করুন। একটি সাধারণ স্ট্রিং তুলনা টাইমিং তথ্য ফাঁস করে। একটি টাইমিং-সেফ ফাংশন ব্যবহার করুন।
- সাইনড স্ট্রিংয়ে টাইমস্ট্যাম্প অন্তর্ভুক্ত করুন।
timestamp.bodyসাইন করলে আপনি পুরনো রিকোয়েস্ট প্রত্যাখ্যান করতে পারেন এবং রিপ্লে অ্যাটাক ব্লক করতে পারেন।
// 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 কল করা, ইনভয়েস তৈরি করা — ব্যাকগ্রাউন্ড জবে হওয়া উচিত। যদি প্রসেসিং প্রোভাইডারের টাইমআউটের চেয়ে বেশি সময় নেয়, তাহলে রিকোয়েস্টটি ব্যর্থ হিসেবে বিবেচিত হয় এবং রিট্রাই হয় যদিও আপনি কাজটি সম্পন্ন করেছেন।
- সিগনেচার এবং টাইমস্ট্যাম্প যাচাই করুন।
- ইভেন্ট আইডিতে ইউনিক কনস্ট্রেইন্ট সহ একটি টেবিলে ইভেন্টটি সন্নিবেশ করুন।
- সাথে সাথে
200ফেরত দিন। - সংরক্ষিত ইভেন্টটি অ্যাসিনক্রোনাসভাবে প্রসেস করুন, এটি সম্পন্ন হিসেবে চিহ্নিত করুন।
আইডেম্পোটেন্সি: ডুপ্লিকেটের আসল সমাধান
যেহেতু রিট্রাই ঘটে, তাই আপনার হ্যান্ডলারকে দুইবার চালানো নিরাপদ হতে হবে। ইভেন্ট আইডি হলো স্বাভাবিক আইডেম্পোটেন্সি কী।
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 ফেরত দিন এবং রিট্রাইকে তার কাজ করতে দিন।
প্রোডাকশনের জন্য ব্যবহারিক চেকলিস্ট
- শুধুমাত্র HTTPS ব্যবহার করুন; কখনও প্লেইন HTTP-তে ওয়েবহুক গ্রহণ করবেন না।
- সাইনিং সিক্রেট আপনার সিক্রেট ম্যানেজারে সংরক্ষণ করুন এবং রোটেশন সমর্থন করুন — অনেক প্রোভাইডার দুটি সক্রিয় সিক্রেটের অনুমতি দেয়।
- প্রতিটি রিকোয়েস্টের জন্য ইভেন্ট আইডি, ধরন, সিগনেচার ফলাফল এবং প্রসেসিং ফলাফল লগ করুন।
- রিপ্লে ব্লক করতে একটি টলারেন্স উইন্ডো সেট করুন (সাধারণত পাঁচ মিনিট)।
- শুধুমাত্র অ্যাপ্লিকেশন কোডে নয়, ডাটাবেস স্তরে হ্যান্ডলার আইডেম্পোটেন্ট করুন।
- ব্যর্থতার হার বা প্রসেসিং ল্যাগ একটি থ্রেশহোল্ড অতিক্রম করলে সতর্কতা দিন।
- সাপোর্ট স্টাফের জন্য একটি ম্যানুয়াল রিপ্লে এন্ডপয়েন্ট প্রদান করুন।
লোকালি ওয়েবহুক টেস্ট করা
আপনি localhost-এ সহজে একটি পাবলিক POST পেতে পারেন না। বিকল্প: একটি টানেলিং টুল যা আপনার ডেভ পোর্ট এক্সপোজ করে, প্রোভাইডারের CLI যদি থাকে, অথবা একটি ছোট স্ক্রিপ্ট যা আপনার হ্যান্ডলারে একটি সাইনড পেলোড পাঠায় যাতে আপনি যাচাইয়ের পথটি পরীক্ষা করতে পারেন।
সবচেয়ে মূল্যবান পরীক্ষা হলো ডুপ্লিকেট: একই ইভেন্ট দুবার পাঠান এবং নিশ্চিত করুন যে আপনার সিস্টেম একই অবস্থায় শেষ হয়। তারপর একটি পুরনো টাইমস্ট্যাম্প সহ একটি ইভেন্ট পাঠান এবং নিশ্চিত করুন যে এটি প্রত্যাখ্যাত হয়। তারপর বডির এক বাইট পরিবর্তন করুন এবং নিশ্চিত করুন যে সিগনেচার চেক ব্যর্থ হয়।
পেলোড ডিবাগিং
ওয়েবহুক বডি JSON, এবং ত্রুটিপূর্ণ বা গভীরভাবে নেস্টেড পেলোড লগে পড়া কষ্টকর। পার্সিং কোড লেখার আগে কাঠামো দ্রুত পরিদর্শন করতে একটি ফরম্যাটার সাহায্য করে। JSON ফরম্যাটার ব্রাউজারে চলে, তাই আপনি গ্রাহকের ডেটা সার্ভারে না পাঠিয়ে একটি ক্যাপচার করা পেলোড পেস্ট করতে পারেন।
সাধারণ জিজ্ঞাসা
ওয়েবহুক এবং API-এর মধ্যে পার্থক্য কী?
একটি API পুল-ভিত্তিক: আপনার কোড যখন ডেটা প্রয়োজন তখন প্রোভাইডারকে কল করে। একটি ওয়েবহুক পুশ-ভিত্তিক: একটি ইভেন্ট ঘটলে প্রোভাইডার আপনার এন্ডপয়েন্টকে কল করে। বেশিরভাগ ইন্টিগ্রেশন উভয়ই ব্যবহার করে — ইভেন্ট নোটিফিকেশনের জন্য ওয়েবহুক এবং সম্পূর্ণ বিবরণ আনতে বা কাজ সম্পাদনের জন্য API।
কেন আমার HMAC সিগনেচার কখনও মেলে না?
সাধারণ কারণ হলো র' বাইটের পরিবর্তে পুনরায় সিরিয়ালাইজ করা বডি সাইন করা। হোয়াইটস্পেস, কী-এর ক্রম এবং ইউনিকোড এস্কেপিং সবই হ্যাশ পরিবর্তন করে। যেকোনো JSON মিডলওয়্যারের আগে র' রিকোয়েস্ট বডি পড়ুন, এবং নিশ্চিত করুন যে সিক্রেট এবং হ্যাশ অ্যালগরিদম প্রোভাইডারের ডকুমেন্টেশনের সাথে মেলে।
ওয়েবহুক রিট্রাই কি গ্যারান্টিযুক্ত?
না। প্রোভাইডাররা সাধারণত এক্সপোনেনশিয়াল ব্যাকঅফের সাথে একটি সীমিত সময়ের জন্য রিট্রাই করে, তারপর হাল ছেড়ে দেয়। ওয়েবহুককে সত্যের উৎসের পরিবর্তে একটি দ্রুত নোটিফিকেশন চ্যানেল হিসেবে বিবেচনা করুন: প্রোভাইডারের API-এর সাথে পর্যায়ক্রমে মিলিয়ে নিন যাতে মিস হওয়া ইভেন্টগুলি শেষ পর্যন্ত সংশোধন হয়।
আপনি যদি আজ একটি ওয়েবহুক রিসিভার তৈরি বা ডিবাগ করছেন, তাহলে সিগনেচার যাচাই এবং আইডেম্পোটেন্ট স্টোরেজ লক ডাউন করে শুরু করুন — এই দুটি পরিবর্তন বাস্তব জগতের বেশিরভাগ ওয়েবহুক ঘটনা দূর করে।