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

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

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

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

SaleMag-এ আপনি নিজে সেট করেন এক ধরনের ওয়েবহুক: আউটগোয়িং ইভেন্ট ওয়েবহুক। এর বাইরে কিছু প্ল্যাটফর্ম ওয়েবহুক আছে, যা SaleMag নিজেই সেট করে:

আপনার সিস্টেম থেকে SaleMag-এ ডেটা পাঠানোর কাজ হয় REST API দিয়ে; নিচে দেখুন।

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।

আমার সিস্টেম থেকে SaleMag-এ ডেটা পাঠাব কীভাবে?

REST API দিয়ে। SaleMag-এ ইনকামিং ওয়েবহুক URL নেই, তাই আপনার ওয়েবসাইট, ERP বা অর্ডার সিস্টেম বেয়ারার টোকেন দিয়ে সরাসরি API কল করে:

Zapier, Make বা n8n-এর মতো টুলও একইভাবে কাজ করে: SaleMag-এর আউটগোয়িং ওয়েবহুক নেয়, আর API কল করে। অর্ডার আপডেটের টেমপ্লেট কেমন লিখলে অনুমোদন পায়, দেখুন WhatsApp-এ অর্ডার স্ট্যাটাস আপডেট।

SaleMag কি অর্ডারের ডেটা আমার সিস্টেমে পাঠায়?

না। আউটগোয়িং ওয়েবহুকে অর্ডার বা কার্টের কোনো ইভেন্ট নেই। স্টোরের অর্ডার আসে আপনার Shopify, WooCommerce বা BigCommerce স্টোর থেকেই, তাই অর্ডারের ডেটা সরাসরি স্টোর থেকে নেওয়াই সহজ। চ্যাটে নেওয়া অর্ডার থাকে SaleMag-এর Orders পেজে।

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

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

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

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

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

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