WhatsApp ওয়েবহুক: সাইন করা ইভেন্ট ও ইনকামিং ট্রিগার

আপনার অর্ডার সিস্টেম জানে কখন অর্ডার এলো। আপনার CRM-এর জানা দরকার কখন কাস্টমার WhatsApp-এ লিখলেন। দুটো যুক্ত না থাকলে কাউকে এক স্ক্রিন দেখে আরেক স্ক্রিনে টাইপ করতে হয়, আর কিছু না কিছু বাদ পড়ে। প্রতি মিনিটে API-তে খোঁজ নেওয়া ধীর, আর রিকোয়েস্টও নষ্ট হয়।

ওয়েবহুক হলো একটা HTTP রিকোয়েস্ট, যা কোনো ঘটনা ঘটার সাথে সাথে এক সিস্টেম আরেক সিস্টেমকে পাঠায়। SaleMag দুই দিকেই ওয়েবহুক ব্যবহার করে: নতুন মেসেজ, কন্টাক্ট আর শেষ হওয়া ক্যাম্পেইনের খবর আপনার সিস্টেমকে দেয়, আর আপনার সিস্টেম SaleMag-এর অটোমেশন চালু করতে পারে।

SaleMag-এ কত ধরনের ওয়েবহুক আছে?

SaleMag-এ তিন ধরনের ওয়েবহুক আছে, সাথে কিছু প্ল্যাটফর্ম ওয়েবহুক, যা SaleMag নিজেই সেট করে:

SaleMag-এর আউটগোয়িং ওয়েবহুক কোন কোন ইভেন্ট পাঠায়?

SaleMag-এর আউটগোয়িং ওয়েবহুক তিনটি ইভেন্ট পাঠায়। প্রতিটি এন্ডপয়েন্টে ইভেন্ট বাছাই করা যায়; কোনো ইভেন্ট না বাছলে সবগুলোই আসে।

CSV ইমপোর্ট, স্টোর সিঙ্ক বা POST /api/v1/contacts দিয়ে আসা কন্টাক্টে contact.created যায় না।

একটা message.received ডেলিভারি দেখতে এমন:

{
  "event": "message.received",
  "message": {
    "id": 9812,
    "conversation_id": 311,
    "direction": "in",
    "channel": "whatsapp",
    "body": "Ei dress ta koto?",
    "sent_at": "2026-10-24T09:15:02+00:00"
  },
  "timestamp": "2026-10-24T09:15:03+00:00"
}

campaign.completed-এ totals-এর ভেতরে থাকে total, queued, sent, delivered, read, failed, clicked আর unsubscribed-এর সংখ্যা।

প্রতিটি ডেলিভারিতে কোন কোন হেডার থাকে?

প্রতিটি ডেলিভারি JSON বডিসহ একটা HTTP POST, সাথে এই হেডারগুলো:

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

আপনার সাইনিং সিক্রেট দিয়ে {t}.{raw body}-এর HMAC-SHA256 hex হিসেবে বের করুন, তারপর v1-এর সাথে মেলান। সিক্রেট শুরু হয় whsec_ দিয়ে; প্রিফিক্সসহ পুরো স্ট্রিংটাই ব্যবহার করুন। সবসময় যেমন এসেছে তেমন raw body হ্যাশ করুন, নতুন করে এনকোড করা কপি নয়।

import crypto from "node:crypto"

// rawBody: the request body as a string, exactly as received
export function verifySaleMagWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=", 2)))
  if (!parts.t || !parts.v1) return false
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) 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)
}

একই যাচাই PHP-তে:

$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, $secret);
$valid = isset($sig['v1']) && hash_equals($expected, $sig['v1']);

প্রতিটি চেষ্টা, রিট্রাইসহ, নতুন টাইমস্ট্যাম্প দিয়ে আবার সাইন হয়। তাই পুরোনো টাইমস্ট্যাম্প নিশ্চিন্তে বাতিল করতে পারেন।

আমার এন্ডপয়েন্ট বন্ধ থাকলে কী হয়?

আপনার এন্ডপয়েন্ট ১০ সেকেন্ডের মধ্যে যেকোনো 2xx স্ট্যাটাস দিলে SaleMag ডেলিভারি সফল ধরে। বাকি সব ক্ষেত্রে এই সময়সূচিতে আবার চেষ্টা হয়:

প্রতিটি চেষ্টা ডেলিভারি লগে সেভ হয়: ইভেন্ট, HTTP স্ট্যাটাস, কততম চেষ্টা আর সময়। Webhooks পেজে প্রতিটি এন্ডপয়েন্টের শেষ পাঁচটা দেখা যায়, আর View deliveries-এ পুরো তালিকা। প্রাইভেট বা লোকাল নেটওয়ার্কের ঠিকানায় যাওয়া URL ব্লক হয়, আবার চেষ্টাও হয় না।

ধীর সফল রেসপন্সের পরেও রিট্রাই আসতে পারে। তাই আপনার রিসিভার এমনভাবে বানান যাতে দুবার চললেও সমস্যা না হয়: অবজেক্টের id রেখে দিন, আগে সামলানো হলে বাদ দিন।

ওয়েবহুক এন্ডপয়েন্ট কীভাবে সামলাব?

অ্যাপের Webhooks পেজ থেকে, অথবা কোড দিয়ে:

• তৈরি, এডিট, বন্ধ বা ডিলিট করুন। এই পেজ খুলতে টিম মেম্বারের ডেভেলপার পারমিশন লাগে।
• সিক্রেট রোটেট করুন। পুরোনো সিক্রেট সাথে সাথে বন্ধ হয়ে যায়, তাই রিসিভার তখনই আপডেট করুন।
• Send test। ওই এন্ডপয়েন্টে একটা test.ping পাঠায়।
• API থেকে। webhooks:write স্কোপের টোকেন দিয়ে /api/v1/webhooks-এ GET, POST আর DELETE। তৈরির রেসপন্সে সিক্রেট একবারই আসে। দেখুন REST API।

ইনকামিং ওয়েবহুক কীভাবে অটোমেশন চালু করে?

অটোমেশনে Webhook Received ট্রিগার দিলে SaleMag এমন একটা URL দেখায়:

https://YOUR-SALEMAG-DOMAIN/api/webhooks/automation/{token}

প্রতিটি অটোমেশনের আলাদা টোকেন, আর অটোমেশনটি অ্যাক্টিভ থাকতে হবে। রিকোয়েস্ট এলে SaleMag সিক্রেট দেওয়া থাকলে সিগনেচার যাচাই করে, আপনার ইভেন্ট ফিল্টার মেলায়, একই রিকোয়েস্ট দুবার এলে বাদ দেয়, কন্টাক্ট খোঁজে, তারপর ফ্লো চালু করে। এরপর পেলোড টোকেন হিসেবে পাওয়া যায়, যেমন {{context.payload.order.number}}।

ট্রিগারের তিনটি প্রিসেট:

এর উপর কিছু বানালে যা জানা দরকার:

• বডি। JSON, ফর্ম ডেটা বা কোয়েরি প্যারামিটার। SaleMag ১ MB পর্যন্ত পড়ে।
• সিগনেচার। সিক্রেট দিলে SaleMag raw body-র HMAC-SHA256 যাচাই করে। hex বা base64 দুটোই চলে, sha256= প্রিফিক্স থাকুক বা না থাকুক। সাইন ছাড়া রিকোয়েস্ট বাতিল করতে "require signature" চালু করুন।
• ইভেন্ট ফিল্টার। কোন ইভেন্ট নেবেন তার তালিকা দিন। শেষে * দিলে প্রিফিক্স মেলে, যেমন orders/* নেবে orders/create আর orders/paid।
• ডুপ্লিকেট। আগে দেখা ডেলিভারি আইডির রিকোয়েস্ট বাদ পড়ে। ডেলিভারি আইডি হেডার না থাকলে হুবহু একই বডিকে ডুপ্লিকেট ধরা হয়। তাই দুটো আসল ইভেন্টের বডি একই হতে পারলে ডেলিভারি আইডি পাঠান।
• কন্টাক্ট। SaleMag আগে ইমেইল, তারপর ফোন দিয়ে কন্টাক্ট মেলায়। অন্য পাথ ম্যাপ করা যায়, আর নতুন মানুষের জন্য "create contact" চালু করা যায়। কন্টাক্ট না পেলেও ফ্লো চলে।
• ডেলিভারি লগ। প্রতিটি রিকোয়েস্ট স্ট্যাটাস, পেলোড আর হেডারসহ লগ হয়। বিল্ডার আসল পেলোড দেখে টোকেন সাজেস্ট করে, আর Replay লগের একটা ডেলিভারি আবার চালায়।

URL-টি GET-এ {"status":"ready"} দেয়, তাই "test this URL" বাটন পাস করে। রেসপন্সগুলো:

অর্ডার আপডেটের টেমপ্লেট কেমন লিখলে অনুমোদন পায়, দেখুন WhatsApp-এ অর্ডার স্ট্যাটাস আপডেট।

অর্ডারের ডেটা আমার নিজের সিস্টেমে কীভাবে পাঠাব?

অটোমেশনের ভেতরে Call Webhook ধাপ ব্যবহার করুন। অর্ডার ইভেন্ট আউটগোয়িং ওয়েবহুকে যায় না, কিন্তু Order Placed, Order Shipped / Fulfilled বা Cart Abandoned ট্রিগারের অটোমেশন সেই মুহূর্তে আপনার URL-এ কল করতে পারে:

• মেথড GET, POST, PUT, PATCH বা DELETE, সাথে আপনার নিজের হেডার।
• টোকেন দিয়ে লেখা JSON বডি, যেমন {{context.order_number}}। GET ছাড়া বাকি সব মেথডে SaleMag বডিতে রানের context অবজেক্ট যোগ করে।
• ১০ সেকেন্ডের টাইমআউট। রেসপন্সের স্ট্যাটাস রানে webhook_status হিসেবে সেভ হয়।

এই ধাপ SaleMag সাইন করে না। আপনার এন্ডপয়েন্টে যাচাই লাগলে নিজের একটা সিক্রেট হেডার যোগ করুন। অর্ডার ট্রিগার আসে যুক্ত করা Shopify, WooCommerce আর BigCommerce স্টোর আর চ্যাট অর্ডার থেকে। সব ট্রিগার আর ধাপ দেখতে অটোমেশন ফ্লো বিল্ডার দেখুন।

SaleMag ওয়েবহুক কী করে না?

• অর্ডার, কার্ট, লিড বা মেসেজ স্ট্যাটাসের ইভেন্ট আউটগোয়িং ওয়েবহুকে যায় না। শুধু উপরের তিনটি ইভেন্টই SaleMag থেকে বের হয়।
• Zapier, Make বা n8n-এর নিজস্ব অ্যাপ নেই। সাধারণ ওয়েবহুক দিয়ে কাজ করে।
• Call Webhook ধাপে সিগনেচার নেই।
• আউটগোয়িং ডেলিভারি হাতে আবার পাঠানোর ব্যবস্থা নেই। রিট্রাই নিজে থেকে হয়, আর Replay শুধু ইনকামিং অটোমেশন ওয়েবহুকে।

SaleMag ওয়েবহুক কাদের জন্য?

ডেভেলপার আর এজেন্সি, যারা SaleMag-কে ওয়েবসাইট, ERP, POS, CRM বা নো-কোড টুলের সাথে যুক্ত করেন। আর সেই শপগুলোর জন্য, যারা চান নিজেদের অর্ডার সিস্টেমের ঘটনার সাথে সাথে WhatsApp মেসেজ যাক। কোড থেকে মেসেজ পাঠানো বা ডেটা পড়ার কাজ REST API দিয়ে হয়।

কীভাবে শুরু করবেন?

SaleMag অ্যাকাউন্ট খুলুন, Webhooks পেজে আপনার এন্ডপয়েন্ট যোগ করুন, তারপর Send test চাপুন। প্ল্যানের দাম দামের পেজে।