خطافات الويب
استلم أحداث التفعيل على خادمك في الوقت الفعلي، وتحقّق من الترويسة SmsGrab-Signature، وافهم إعادة المحاولات وعمليات التسليم التجريبية والإيقاف التلقائي.
في هذه الصفحة
ترسل خطافات الويب الأحداث إلى خادمك لحظة وقوعها، فلا تحتاج إلى الاستعلام. ينتمي خطاف الويب إلى مفتاح 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، لا يُعرض إلا مرة واحدة. يمكنك تغييره لاحقًا، وهذا يتطلب كلمة المرور أيضًا.
شكل التسليم
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 ثانية عن ساعتك، وقارن التواقيع في زمن ثابت.
[$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.
أجب بسرعة
أجب بأي حالة 2xx خلال 10 ثوانٍ وأنجز العمل البطيء بعد ذلك، مثلًا في طابور. لا تُتبَع عمليات إعادة التوجيه.
إعادة المحاولات
يُعاد التسليم الفاشل بعد دقيقة، و5 دقائق، و15 دقيقة، وساعة، و3 ساعات، و6 ساعات، و12 ساعة، و24 ساعة. تكرر إعادة المحاولة معرّف الحدث id نفسه، لذا احفظ المعرّفات التي عالجتها وتجاوز المكررات. تصل أحداث التفعيل الواحد بالترتيب.
الإيقاف التلقائي
- الرد بـ
410 Goneيوقف خطاف الويب فورًا. - بعد 50 محاولة فاشلة متتالية على مدى 24 ساعة على الأقل، يُوقف خطاف الويب ويصلك إشعار. أصلح نقطة النهاية، ثم أعد تشغيل خطاف الويب.
- إبطال مفتاح يوقف خطافات الويب الخاصة به.
الاختبار وإعادة التسليم
أرسل حدث webhook.test من صفحة خطاف الويب لترى فورًا رمز الحالة وزمن الاستجابة وأي خطأ. تحتفظ قائمة عمليات التسليم بكل تسليم لمدة 30 يومًا، ويمكنك إرسال أي منها مجددًا.
هل كان هذا المقال مفيدًا؟
شكرًا! يسعدنا أنه ساعدك.