اختيار اللغة

خطافات الويب

استلم أحداث التفعيل على خادمك في الوقت الفعلي، وتحقّق من الترويسة SmsGrab-Signature، وافهم إعادة المحاولات وعمليات التسليم التجريبية والإيقاف التلقائي.

في هذه الصفحة
  1. الأحداث
  2. إنشاء خطاف ويب
  3. شكل التسليم
  4. تحقّق من التوقيع
  5. أجب بسرعة
  6. إعادة المحاولات
  7. الإيقاف التلقائي
  8. الاختبار وإعادة التسليم

ترسل خطافات الويب الأحداث إلى خادمك لحظة وقوعها، فلا تحتاج إلى الاستعلام. ينتمي خطاف الويب إلى مفتاح API واحد. يستلم أحداث الأرقام المشتراة بهذا المفتاح، إضافة إلى تنبيهات انخفاض رصيد حسابك.

الأحداث

الحدث متى
activation.created تم شراء رقم
activation.code_received كل رسالة SMS جديدة، مع كل الرسائل حتى الآن
activation.completed أنهيته أنت، أو انتهى الوقت بعد وصول رمز
activation.cancelled أُلغي قبل الرمز، واسترُد
activation.expired لم يصل رمز في الوقت، واسترُد
activation.refunded أي استرداد للمبلغ المخصوم
balance.low انخفض رصيدك تحت الحد الذي حددته
webhook.test تسليم تجريبي بدأته أنت

إنشاء خطاف ويب

في الحساب > المطوّرون، افتح مفتاحًا وأضف خطاف ويب بعنوان URL والأحداث التي تريدها ووصف اختياري. يمكن أن يكون لكل مفتاح حتى 3 خطافات ويب.

يجب أن يكون عنوان URL:

  • يبدأ بـ https://؛
  • يستخدم اسم مضيف، لا عنوان IP؛
  • يؤدي إلى عنوان عام. تُرفض الشبكات الخاصة وlocalhost والنطاقات المشابهة.

تحصل على سر توقيع يبدأ بـ whsec_. مثل مفتاح API، لا يُعرض إلا مرة واحدة. يمكنك تغييره لاحقًا، وهذا يتطلب كلمة المرور أيضًا.

شكل التسليم

HTTP
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، وهو HMAC-SHA256 لـ t ونقطة ونص الطلب الخام، بمفتاح هو سرك. ارفض عمليات التسليم التي يبتعد طابعها الزمني أكثر من 300 ثانية عن ساعتك، وقارن التواقيع في زمن ثابت.

PHP
[$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);
Python
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", ""))
JavaScript
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.

أجب بسرعة

أجب بأي حالة 2xx خلال 10 ثوانٍ وأنجز العمل البطيء بعد ذلك، مثلًا في طابور. لا تُتبَع عمليات إعادة التوجيه.

إعادة المحاولات

يُعاد التسليم الفاشل بعد دقيقة، و5 دقائق، و15 دقيقة، وساعة، و3 ساعات، و6 ساعات، و12 ساعة، و24 ساعة. تكرر إعادة المحاولة معرّف الحدث id نفسه، لذا احفظ المعرّفات التي عالجتها وتجاوز المكررات. تصل أحداث التفعيل الواحد بالترتيب.

الإيقاف التلقائي

  • الرد بـ 410 Gone يوقف خطاف الويب فورًا.
  • بعد 50 محاولة فاشلة متتالية على مدى 24 ساعة على الأقل، يُوقف خطاف الويب ويصلك إشعار. أصلح نقطة النهاية، ثم أعد تشغيل خطاف الويب.
  • إبطال مفتاح يوقف خطافات الويب الخاصة به.

الاختبار وإعادة التسليم

أرسل حدث webhook.test من صفحة خطاف الويب لترى فورًا رمز الحالة وزمن الاستجابة وأي خطأ. تحتفظ قائمة عمليات التسليم بكل تسليم لمدة 30 يومًا، ويمكنك إرسال أي منها مجددًا.

هل كان هذا المقال مفيدًا؟

هل ما زلت تحتاج إلى مساعدة؟

راسلنا. نرد على كل رسالة، عادة خلال ساعات قليلة.

أو راسلنا على support@smsgrab.com