ویب ہُکس

ویب ہُکس واقعات کو ہوتے ہی آپ کے سرور پر بھیجتے ہیں، اس لیے آپ کو بار بار پوچھنا نہیں پڑتا۔ ہر ویب ہُک ایک API کلید سے تعلق رکھتا ہے۔ یہ اس کلید سے خریدے گئے نمبروں کے واقعات، اور آپ کے اکاؤنٹ کے کم بیلنس کے الرٹس وصول کرتا ہے۔

واقعات

ویب ہُک بنائیں

اکاؤنٹ > ڈویلپرز میں کوئی کلید کھولیں اور URL، مطلوبہ واقعات اور اختیاری تفصیل کے ساتھ ویب ہُک شامل کریں۔ ہر کلید کے 3 تک ویب ہُکس ہو سکتے ہیں۔

URL کو لازماً:

• https:// سے شروع ہونا چاہیے؛
• IP پتے کے بجائے ہوسٹ نام استعمال کرنا چاہیے؛
• عوامی پتے تک جانا چاہیے۔ نجی نیٹ ورکس، localhost اور ملتی جلتی رینجز رد کی جاتی ہیں۔

آپ کو whsec_ سے شروع ہونے والا دستخطی راز ملتا ہے۔ API کلید کی طرح یہ بھی صرف ایک بار دکھایا جاتا ہے۔ آپ اسے بعد میں بدل سکتے ہیں، جس کے لیے بھی پاس ورڈ درکار ہوتا ہے۔

ڈیلیوری کیسی دکھتی ہے

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SmsGrab-Webhooks/1.0
SmsGrab-Event: activation.code_received
SmsGrab-Delivery: 9f7d6c1e-2b44-4c1a-8f0e-6a3d2c1b0e9f
SmsGrab-Signature: t=1790503200,v1=3b9a0c…

{ "id": "evt_4e1f…", "type": "activation.code_received", "created_at": "2026-09-27T10:06:12.004Z",
  "api_version": "2026-09-27", "data": { "activation": { "id": "5c1d0c2e-…", "status": "CODE_RECEIVED" } } }

دستخط کی تصدیق

SmsGrab-Signature میں ایک ٹائم اسٹیمپ t اور v1 ہوتا ہے، جو آپ کے راز کے ساتھ t، ایک نقطے اور خام درخواست باڈی کا HMAC-SHA256 ہے۔ ان ڈیلیوریز کو رد کریں جن کا ٹائم اسٹیمپ آپ کی گھڑی سے 300 سیکنڈ سے زیادہ دور ہو، اور دستخطوں کا موازنہ مستقل وقت میں کریں۔

[$t, $v1] = (function (string $h): array {
    parse_str(str_replace(',', '&', $h), $p);
    return [(int) ($p['t'] ?? 0), (string) ($p['v1'] ?? '')];
})($_SERVER['HTTP_SMSGRAB_SIGNATURE'] ?? '');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t.'.'.$body, getenv('SMSGRAB_WEBHOOK_SECRET'));
$ok = abs(time() - $t) <= 300 && hash_equals($expected, $v1);

import hmac, hashlib, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - t) <= 300 and hmac.compare_digest(expected, parts.get("v1", ""))

import crypto from 'node:crypto';

export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t ?? 0);
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'utf8');
  return Math.abs(Date.now() / 1000 - t) <= 300 && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given);
}

JSON پارس کرنے سے پہلے ہمیشہ خام باڈی کو بالکل ویسا ہی جانچیں جیسا وصول ہوا۔

جلد جواب دیں

10 سیکنڈ کے اندر کسی بھی 2xx حیثیت سے جواب دیں اور سست کام بعد میں کریں، مثلاً قطار میں۔ ری ڈائریکٹس پر عمل نہیں ہوتا۔

دوبارہ کوششیں

ناکام ڈیلیوری 1 منٹ، 5 منٹ، 15 منٹ، 1 گھنٹہ، 3 گھنٹے، 6 گھنٹے، 12 گھنٹے اور 24 گھنٹے بعد دوبارہ کی جاتی ہے۔ دوبارہ کوشش میں واقعے کا وہی id ہوتا ہے، اس لیے پراسیس کیے گئے آئی ڈیز یاد رکھیں اور دہرائے ہوئے چھوڑ دیں۔ ایک ایکٹیویشن کے واقعات ترتیب سے آتے ہیں۔

خودکار بندش

• 410 Gone کا جواب ویب ہُک کو فوراً بند کر دیتا ہے۔
• کم از کم 24 گھنٹوں میں لگاتار 50 ناکام کوششوں کے بعد ویب ہُک بند ہو جاتا ہے اور آپ کو اطلاع ملتی ہے۔ اپنا اینڈ پوائنٹ ٹھیک کریں، پھر ویب ہُک دوبارہ آن کریں۔
• کلید منسوخ کرنے سے اس کے ویب ہُکس بند ہو جاتے ہیں۔

ٹیسٹ اور دوبارہ ڈیلیوری

ویب ہُک کے صفحے سے webhook.test واقعہ بھیجیں تاکہ فوراً اسٹیٹس کوڈ، جواب کا وقت اور کوئی بھی خرابی دیکھ سکیں۔ ڈیلیوری فہرست ہر ڈیلیوری 30 دن تک رکھتی ہے، اور آپ ان میں سے کوئی بھی دوبارہ بھیج سکتے ہیں۔