تجزیہ کرنا

دستخط شدہ ترسیل، اور ایسی ای میل جو کچھ نہیں بتاتی۔

ویب ہک ہر نئے جواب کو آپ کے منتخب کردہ https URL پر بھیج دیتا ہے۔ ہر ترسیل کے ساتھ ایک X-NumoForms-Signature ہیڈر جاتا ہے: sha256= اور اس کے بعد درخواست کے من و عن متن کا HMAC-SHA256، جو اُس ویب ہک کے اپنے خفیہ کلید سے نکالا جاتا ہے، تاکہ آپ کا اینڈ پوائنٹ ثابت کر سکے کہ پیغام ہماری طرف سے آیا ہے۔ اس سے الگ، جواب پہنچنے پر منتخب ای میل پتوں کو اطلاع دی جا سکتی ہے — اور اُن ای میلوں میں جان بوجھ کر کوئی جواب شامل نہیں ہوتا۔

آپ کے اینڈ پوائنٹ پر کیا پہنچتا ہے

فی جواب ایک JSON POST۔ متن میں پانچ فیلڈ ہوتے ہیں اور اس کے سوا کچھ نہیں، اس لیے آپ اندازوں کے بغیر اس کے لیے پارسر لکھ سکتے ہیں۔

فیلڈ	اس میں کیا ہوتا ہے
`event`	response.created
`survey_id`	وہ سروے جس سے یہ جواب تعلق رکھتا ہے۔
`response_id`	اس جواب کی منفرد شناخت۔
`created_at`	جواب کب درج ہوا۔
`answers`	جوابات، سوال کی شناخت کے حساب سے۔

ہیڈر	یہ کس کام کا ہے
`X-NumoForms-Event`	واقعے کا نام۔ آج ایک ہی ہے: response.created۔
`X-NumoForms-Signature`	sha256= اور اس کے بعد درخواست کے من و عن متن کا HMAC-SHA256، ہیکسا ڈیسیمل میں۔
`X-NumoForms-Delivery`	اس ترسیل کی کوشش کی منفرد شناخت، تاکہ آپ دہرائی گئی ترسیل پہچان سکیں۔

ترسیل ایپ کی کسی خاص اسکرین کے بجائے جوابات کی ٹیبل پر لگے ڈیٹابیس ٹرگر سے چلتی ہے۔ یہ بات جتنی لگتی ہے اس سے زیادہ اہم ہے: ایمبیڈ کیے گئے فارم سے آنے والا جواب، ہوسٹ کیے گئے لنک سے آنے والا جواب، اور محفوظ کریں اور جاری رکھیں کے ذریعے کئی دن بعد مکمل کیا گیا ادھورا جواب، سب ایک ہی راستے سے گزرتے ہیں، اس لیے کوئی ایسا راستہ نہیں بچتا جسے جوڑنا ہم بھول گئے ہوں۔

ویب ہک اُس وقت چلتا ہے جب جواب پہنچتا ہے۔ اگر آپ نے منظوریاں فعال کر رکھی ہیں تو یہ منظور یا مسترد کرنے کے فیصلے کا انتظار نہیں کرتا، اور فیصلہ ہو جانے پر دوسری ترسیل نہیں بھیجی جاتی۔ آنے والے پیغام کو ”ایک جواب موجود ہے“ سمجھیں، ”ایک جواب کی حتمی منظوری ہو چکی ہے“ نہیں۔

دستخط اختیاری کیوں نہیں

ویب ہک کا URL ایک ایسا راز ہے جو باہر نکل جاتا ہے۔ وہ کسی ٹکٹ میں پہنچ جاتا ہے، کسی Slack پیغام میں، حوالگی کی دستاویز کے اسکرین شاٹ میں، یا کسی مشترکہ لیپ ٹاپ کی براؤزر ہسٹری میں۔ دستخط کے بغیر جس کسی نے وہ URL دیکھ لیا وہ اس پر جو چاہے بھیج سکتا ہے، اور آپ کے نظام اسے مشاورت کا اصل جواب سمجھ کر درج کر لیں گے۔ کسی منصوبہ بندی کی درخواست پر اعتراضات گننے والی کونسل کے لیے یہ نظریاتی مسئلہ نہیں۔

چنانچہ ہر ترسیل پر دستخط ہوتے ہیں۔ ہر ویب ہک کو اپنا بے ترتیب بنایا ہوا خفیہ کلید ملتا ہے، جو بلڈر میں ”دستخطی خفیہ کلید دکھائیں“ کے پیچھے نظر آتا ہے۔ ہم اُسی کلید سے درخواست کے متن کے ہو بہو بائٹس پر HMAC-SHA256 نکالتے ہیں؛ آپ اپنی نقل سے وہی دوبارہ نکالتے ہیں اور موازنہ کرتے ہیں۔ جعلی درخواست ناکام ہو جاتی ہے، کیونکہ جعل ساز کے پاس وہ کلید نہیں۔

URL کا https ہونا لازمی ہے۔ اس پر عمل فارم میں دی گئی کسی ہدایت سے نہیں بلکہ ڈیٹابیس کی پابندی سے کرایا جاتا ہے، کیونکہ غیر خفیہ کردہ رابطے پر سفر کرنے والا دستخطی خفیہ کلید خفیہ رہتا ہی نہیں۔

Node.js میں ترسیل کی تصدیق

عملی طور پر سب سے زیادہ نقصان دو تفصیلات پہنچاتی ہیں۔ درخواست کا خام متن استعمال کریں، پارس کر کے دوبارہ بنایا ہوا آبجیکٹ نہیں — خالی جگہ کا معمولی فرق بھی ہیش بدل دیتا ہے۔ اور موازنہ مستقل وقت میں کریں، تاکہ کوئی حملہ آور جواب کے وقت سے درست دستخط ایک ایک بائٹ کر کے معلوم نہ کر سکے۔

import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.NOISSIME_WEBHOOK_SECRET;

// rawBody must be the exact bytes received, before any JSON parsing.
// Re-serialising a parsed object changes the whitespace and the check fails.
function isFromNoissime(rawBody, header) {
  if (typeof header !== 'string') return false;

  const expected =
    'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(header);

  // timingSafeEqual throws on a length mismatch, so compare lengths first.
  return a.length === b.length && timingSafeEqual(a, b);
}

اسے کچھ بھی پارس کرنے سے پہلے پکاریں۔ اگر یہ false لوٹائے تو 401 کا جواب دیں اور درخواست پھینک دیں۔ اگر true لوٹائے تو آپ کے پاس ایسا جواب ہے جو صرف آپ ہی کے سروے سے آ سکتا تھا۔

ترسیل کا لاگ

خاموشی سے بند ہو جانے والا ویب ہک بالکل ویسا ہی لگتا ہے جیسے وہ جسے کبھی پکارا ہی نہ گیا ہو: کچھ نہیں ہوتا، اور کوئی چیز آپ کو بتاتی بھی نہیں۔ اس لیے ہر کوشش ترسیل کے لاگ میں لکھی جاتی ہے، اور بلڈر میں ہر ویب ہک کے سامنے آخری HTTP اسٹیٹس دکھایا جاتا ہے — 2xx کے لیے سبز، باقی ہر چیز کے لیے سرخ۔

ترسیل غیر ہم وقت ہوتی ہے، اس لیے اسٹیٹس بھیجنے کے لمحے اندازے سے طے کرنے کے بجائے بعد میں ملایا جاتا ہے۔ آپ کو وہی اسٹیٹس نظر آتا ہے جو آپ کے سرور نے واقعی لوٹایا۔ ہر ویب ہک کو حذف کیے بغیر روکا اور دوبارہ چلایا جا سکتا ہے، اور وصول کرنے والا نظام دوبارہ نصب ہوتے وقت عموماً یہی درکار ہوتا ہے۔

ایک سوچی سمجھی حد: وقفے بڑھاتی ہوئی دوبارہ کوشش موجود نہیں۔ ترسیل کی ایک کوشش کی جاتی ہے، نتیجہ درج ہوتا ہے، اور بات ختم۔ ایسی دوبارہ کوشش کی قطار بنانا جو ترتیب اور تکرار سے تحفظ دونوں کا خیال رکھے، حقیقی کام ہے، اور جو قطار ہم نے بنائی ہی نہیں، اس کا دعویٰ کرنا یہ بات صاف کہہ دینے سے بدتر ہوتا۔ اس دوران جواب کبھی ضائع نہیں ہوتا — وہ ڈیٹابیس میں ہے، تجزیات اور رپورٹنگ میں نظر آتا ہے، اور CSV کے طور پر ایکسپورٹ کیا جا سکتا ہے۔

ناکام ہوتا ہوا ویب ہک جوابات جمع کرنے کا عمل بھی نہیں توڑ سکتا۔ اگر ترسیل میں خرابی آئے تو خرابی لاگ میں لکھی جاتی ہے اور جواب پھر بھی درج ہو جاتا ہے۔ اصل چیز جواب دہندہ کا جواب ہے؛ ترسیل کی کوشش کی جاتی ہے، ضمانت نہیں دی جاتی۔

ای میل اطلاعات، جوابات کے بغیر

وہ پتے شامل کریں جنہیں نئے جوابات کی خبر ملنی چاہیے، اور جواب آنے پر انہیں ای میل چلی جاتی ہے۔ پیغام برانڈ شدہ HTML ہوتا ہے جس کے ساتھ سادہ متن کا متبادل بھی جاتا ہے، کیونکہ صرف متن پڑھنے والے کلائنٹ اور اسپیم فلٹر دونوں سادہ حصہ پڑھتے ہیں۔ اس میں سروے کا نام، اب تک کے جوابات کی کل تعداد اور نتائج کا لنک ہوتا ہے۔

جو اس میں نہیں ہوتا وہ جوابات ہیں۔ یہ کوتاہی نہیں، ایک فیصلہ ہے۔ اطلاعی ای میل کسی ساتھی کو آگے بھیج دی جاتی ہے، مشترکہ میل باکس میں خودکار طور پر جمع ہو جاتی ہے، فون سے ہم آہنگ ہو جاتی ہے اور برسوں بیک اپ میں پڑی رہتی ہے۔ مشاورت کے آزاد متن والے جوابات اس سلسلے میں ڈال دینا ذاتی ڈیٹا کو اُن نظاموں میں بکھیر دیتا ہے جن کی کسی نے جانچ ہی نہیں کی، اور خاموشی سے وہ رسائی کا کنٹرول ختم کر دیتا ہے جو سیکیورٹی کے صفحے پر بیان کیا گیا ہے۔ جواب دہندگان کا ڈیٹا ڈیٹابیس میں رہتا ہے، اور ای میل آپ کو یہ بتاتی ہے کہ جا کر دیکھ لیں۔

ویب ہکس کی طرح اطلاعات بھی ڈیٹابیس ٹرگر سے چلتی ہیں، اس لیے وہ جمع کرانے کے کسی خاص راستے کے بجائے جواب کے پیچھے چلتی ہیں۔ اگر کوئی پتہ درج نہ ہو تو کچھ نہیں بھیجا جاتا اور کوئی کوشش بھی نہیں کی جاتی۔

یہ کیا نہیں کرتا

نہ Zapier کی ایپ، نہ Google Sheets کا کنیکٹر۔
وقفے بڑھاتی ہوئی دوبارہ کوشش نہیں — فی جواب ایک کوشش، اور پھر لاگ۔
response.created کے سوا باہر جانے والا کوئی واقعہ نہیں۔ منظوریوں، ترامیم اور حذف کرنے پر ویب ہک نہیں چلتے۔
سروے بنانے یا جوابات پڑھنے کے لیے اندر آنے والا کوئی API نہیں۔
ترسیل کے لیے اجازت یافتہ IP پتوں کی کوئی فہرست نہیں۔ تصدیق کا کام دستخط کرتے ہیں۔

عام سوالات

میں X-NumoForms-Signature ہیڈر کی تصدیق کیسے کروں؟

اُس ویب ہک کے دستخطی خفیہ کلید سے درخواست کے خام متن کا HMAC-SHA256 نکالیں، اسے ہیکسا ڈیسیمل میں لکھیں، اور اس کے شروع میں ”sha256=“ لگائیں، اور مستقل وقت والے موازنے سے ہیڈر کے ساتھ ملائیں۔ تصدیق JSON پارس کرنے سے پہلے کریں، اور جو نہ ملے اسے 401 کے ساتھ مسترد کر دیں۔

اگر جواب پہنچنے کے وقت میرا اینڈ پوائنٹ بند ہو تو کیا ہوگا؟

ترسیل کی ایک کوشش کی جاتی ہے اور نتیجہ HTTP اسٹیٹس کے ساتھ ترسیل کے لاگ میں درج ہو جاتا ہے۔ وقفے بڑھاتی ہوئی خودکار دوبارہ کوشش موجود نہیں۔ جواب خود کبھی خطرے میں نہیں پڑتا: ویب ہک کی ناکامی جواب کو محفوظ ہونے سے نہیں روک سکتی، اور آپ ڈیٹا ہمیشہ نتائج کے صفحے یا CSV ایکسپورٹ سے حاصل کر سکتے ہیں۔

کیا ایمبیڈ کیے گئے فارم سے جمع کرائے گئے جواب پر بھی ویب ہک چلتا ہے؟

جی ہاں۔ ترسیل ایپ کے کسی خاص صفحے کے بجائے جوابات کی ٹیبل پر لگے ڈیٹابیس ٹرگر سے چلتی ہے، اس لیے جواب جہاں سے بھی آئے یہ ہوتی ہے — ہوسٹ کیے گئے لنک سے، ایمبیڈ کیے گئے فارم سے، یا ایسے ادھورے جواب سے جو ابھی مکمل ہوا ہو۔

کیا میں ویب ہک کسی http:// والے URL پر بھیج سکتا ہوں؟

نہیں۔ ڈیٹابیس کی ایک پابندی URL کے https:// سے شروع ہونے کا تقاضا کرتی ہے، اور بلڈر اس کے علاوہ کچھ قبول نہیں کرتا۔ غیر خفیہ کردہ رابطے پر بھیجا گیا دستخطی خفیہ کلید خفیہ رہتا ہی نہیں۔

کیا اطلاعی ای میلوں میں جواب دہندہ کے جوابات ہوتے ہیں؟

نہیں، اور یہ جان بوجھ کر ہے۔ ای میل بتاتی ہے کہ ایک جواب آیا ہے، سروے کا نام دیتی ہے، اب تک کی کل تعداد بتاتی ہے اور نتائج کا لنک دیتی ہے۔ اطلاعات آگے بھیجی جاتی ہیں اور میل باکس کے بیک اپ میں پڑی رہتی ہیں، اس لیے جواب دہندگان کا ڈیٹا ڈیٹابیس ہی میں رہتا ہے جہاں رسائی کا کنٹرول موجود ہے۔

کیا Zapier کی ایپ یا Google Sheets کا اتصال موجود ہے؟

نہیں۔ آج باہر کی طرف واحد اتصال ویب ہکس ہیں۔ نہ Zapier کی ایپ ہے، نہ Google Sheets کا کنیکٹر، اور دونوں میں سے کسی کی کوئی اعلان کردہ تاریخ نہیں۔

سروے کو اپنے نظاموں سے جوڑ دیں۔

ویب ہک کو کسی https ایڈریس کی طرف موڑ دیں اور ہر جواب وہاں دستخط شدہ پہنچے گا، تاکہ آپ کا نظام ثابت کر سکے کہ یہ ہماری طرف سے آیا ہے، نہ کہ اُس کی طرف سے جسے کہیں سے وہ ایڈریس مل گیا۔ جن پتوں پر جواب آنے کی اطلاع ای میل ہونی چاہیے وہ شامل کر دیں، اور جوابات وہیں ڈیٹابیس میں رہتے ہیں جہاں رسائی کے کنٹرول ہیں۔

ہر ترسیل پر HMAC-SHA256 دستخط
ترسیل کا لاگ، جس میں آخری HTTP اسٹیٹس نظر آتا ہے
ڈیٹابیس ٹرگر سے چلتے ہیں، جواب چاہے کسی بھی راستے سے آئے

بنانا شروع کریں