Webhooks
الـ webhook نقطة نهاية HTTPS على خادمك تستدعيها SMSFabric عند حدوث شيء: تسليم رسالة، أو وصول SMS، أو انقطاع هاتف. تغنيك webhooks عن الاستعلام المتكرر، وهي الطريقة الوحيدة لمعرفة أحداث لم تبدأها أنت، كالرسائل الواردة.
إعداد نقطة النهاية
Section titled “إعداد نقطة النهاية”- أنشئ مسارا يقبل
POSTبمحتوى JSON ويرد بـ2xxخلال 10 ثوان. أجّل العمل البطيء إلى ما بعد الرد، في طابور. - سجّله من المطوّرون ← Webhooks في البوابة (شرح خطوة بخطوة)، أو عبر
POST /v1/webhooks. يحتاج المفتاح إلىwebhooks:manage. - احفظ
signingSecretمن الاستجابة. يبدأ بـwhsec_ولا يظهر إلا مرة واحدة. - أرسل حدثا تجريبيا عبر
POST /v1/webhooks/:id/testوتأكد أن نقطة النهاية تتحقق منه.
curl https://api.smsfabric.com/v1/webhooks \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "description": "Order notifications" }'يجب أن يكون الرابط https. تحل SMSFabric اسم المضيف وترفض العناوين الخاصة وعناوين loopback وlink-local مع 400 ssrf_blocked، عند الحفظ وعند كل إرسال.
الأحداث
Section titled “الأحداث”| الحدث | يُرسل عندما | data |
|---|---|---|
message.queued |
تُقبل رسالة | الرسالة |
message.sent |
تقبل شركة الاتصالات رسالة | الرسالة |
message.delivered |
يؤكد جهاز المستلم التسليم | الرسالة |
message.failed |
يتعذر إرسال رسالة | الرسالة مع errorCode |
message.received |
تصل SMS إلى إحدى شرائحك | الرسالة الواردة |
device.online |
يتصل هاتف | الهاتف (id وname وstatus وbattery وsims…) |
device.offline |
يتوقف هاتف عن الإبلاغ | الهاتف |
verification.approved |
يتطابق رمز تحقق | عملية التحقق (الرقم مقنّع) |
verification.expired |
ينتهي رمز تحقق دون استخدام | عملية التحقق |
verification.blocked |
ترفض الحماية إرسالا | reason وto المقنّع وcountry وprefix وblockId وcreatedAt |
campaign.started |
تبدأ حملة الإرسال | id وname وstatus والأوقات وestimatedDurationMs وprogress |
campaign.completed |
تكتمل حملة أو تُلغى (انظر status) |
مثل campaign.started |
webhook.test |
استدعيت POST /v1/webhooks/:id/test |
{ "message": "This is a test event from SMSFabric." } |
لا يمكن الاشتراك في webhook.test، فهو يذهب فقط إلى نقطة النهاية التي تختبرها. حقول data للرسالة هي حقول GET /v1/messages/:id نفسها دون events، ورموز التحقق تظهر دائما [verification code hidden].
المحتوى والترويسات
Section titled “المحتوى والترويسات”كل إرسال طلب POST مع Content-Type: application/json:
POST /hooks/smsfabric HTTP/1.1Content-Type: application/jsonUser-Agent: SMSFabric-Webhooks/1.0SMSFabric-Signature: t=1795086909,v1=5f0c3a8e9b1d4c7e2a6f8b0d3e5c7a9f1b3d5e7f9a1c3e5b7d9f1a3c5e7b9d1fSMSFabric-Event-Id: evt_c7e9g2i4k6m8o1q3s5u7w9y2
{"id":"evt_c7e9g2i4k6m8o1q3s5u7w9y2","type":"message.delivered","createdAt":"2026-11-19T10:15:09.455Z","orgId":"org_n5q8t1w4z7c0f3i6l9o2r5u8","data":{"id":"msg_q8v2k4n6p1r3t5w7y9z0b2c4","status":"delivered","to":"+201001234567","metadata":{"orderId":"1042"}}}| الحقل | المعنى |
|---|---|
id |
معرّف الحدث (evt_…)، وهو نفسه قيمة الترويسة SMSFabric-Event-Id. |
type |
أحد الأحداث أعلاه. |
createdAt |
وقت وقوع الحدث بصيغة ISO 8601 وتوقيت UTC. |
orgId |
مؤسستك. |
data |
الكائن الذي يخصه الحدث. |
التحقق من التواقيع
Section titled “التحقق من التواقيع”يستطيع أي أحد إرسال طلب إلى رابط عام. قبل أن تتصرف بناء على طلب، تأكد أن SMSFabric أرسلته وأنه لم يُعد إرساله لاحقا.
الترويسة SMSFabric-Signature بالشكل t=<unix seconds>,v1=<hex>، حيث v1 هو HMAC-SHA256 للنص <t>.<raw body> بمفتاح سر التوقيع الخاص بك. للتحقق:
- اقرأ محتوى الطلب الخام كما وصل تماما. تحليل JSON ثم إعادة تسلسله يغير البايتات ويفسد التوقيع.
- قسّم الترويسة عند
,وخذtوكل قيمv1. - ارفض الطلب إذا ابتعد
tأكثر من 300 ثانية عن ساعتك. - احسب
HMAC-SHA256(secret, t + "." + rawBody)بصيغة hex وقارنه بـv1مقارنة في زمن ثابت. - رد بـ
400(أو401) إذا لم يتطابق، ولا تعالج الحدث.
كل إعادة محاولة تُوقّع من جديد بقيمة t جديدة، فتجتاز المحاولة المتأخرة نافذة الـ 300 ثانية.
import express from 'express';import { SMSFabric, SignatureVerificationError } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const secret = process.env.SMSFABRIC_WEBHOOK_SECRET ?? '';const app = express();
// express.raw keeps the body as a Buffer: verify the bytes as received.app.post('/hooks/smsfabric', express.raw({ type: 'application/json' }), (req, res) => { try { const event = sf.webhooks.constructEvent(req.body, req.header('SMSFabric-Signature'), secret); res.sendStatus(200); void handle(event.id, event.type, event.data); // do the work after answering } catch (err) { if (err instanceof SignatureVerificationError) return res.sendStatus(400); throw err; }});
async function handle(id: string, type: string, data: unknown): Promise<void> { console.log(id, type, data);}
app.listen(3000);import { createHmac, timingSafeEqual } from 'node:crypto';import express from 'express';
const secret = process.env.SMSFABRIC_WEBHOOK_SECRET ?? '';const TOLERANCE_SEC = 300;
function verify(rawBody: Buffer, header: string | undefined): boolean { if (!header) return false; let t = NaN; const sigs: string[] = []; for (const part of header.split(',')) { const [key, value] = part.split('=', 2); if (key === 't') t = Number(value); if (key === 'v1' && value) sigs.push(value); } if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SEC) return false; const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest(); return sigs.some((sig) => { const given = Buffer.from(sig, 'hex'); return given.length === expected.length && timingSafeEqual(given, expected); });}
const app = express();app.post('/hooks/smsfabric', express.raw({ type: 'application/json' }), (req, res) => { if (!verify(req.body as Buffer, req.header('SMSFabric-Signature'))) return res.sendStatus(400); const event = JSON.parse((req.body as Buffer).toString('utf8')); res.sendStatus(200); console.log(event.id, event.type);});app.listen(3000);import hashlibimport hmacimport jsonimport osimport time
from flask import Flask, abort, request
SECRET = os.environ["SMSFABRIC_WEBHOOK_SECRET"].encode()TOLERANCE_SEC = 300app = Flask(__name__)
def verify(raw_body: bytes, header: str | None) -> bool: if not header: return False t, sigs = None, [] for part in header.split(","): key, _, value = part.partition("=") if key == "t" and value.isdigit(): t = int(value) elif key == "v1": sigs.append(value) if t is None or abs(time.time() - t) > TOLERANCE_SEC: return False expected = hmac.new(SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, sig) for sig in sigs)
@app.post("/hooks/smsfabric")def smsfabric_hook(): raw = request.get_data() # the raw bytes, before any JSON parsing if not verify(raw, request.headers.get("SMSFabric-Signature")): abort(400) event = json.loads(raw) print(event["id"], event["type"]) return "", 200<?php$secret = getenv('SMSFABRIC_WEBHOOK_SECRET');$tolerance = 300;
$raw = file_get_contents('php://input'); // the raw body, before json_decode$header = $_SERVER['HTTP_SMSFABRIC_SIGNATURE'] ?? '';
$t = null;$sigs = [];foreach (explode(',', $header) as $part) { [$key, $value] = array_pad(explode('=', $part, 2), 2, ''); if ($key === 't' && ctype_digit($value)) { $t = (int) $value; } elseif ($key === 'v1') { $sigs[] = $value; }}
$expected = $t === null ? '' : hash_hmac('sha256', $t . '.' . $raw, $secret);$valid = $t !== null && abs(time() - $t) <= $tolerance;$matched = false;foreach ($sigs as $sig) { $matched = $matched || hash_equals($expected, $sig);}
if (!$valid || !$matched) { http_response_code(400); exit;}
$event = json_decode($raw, true);http_response_code(200);error_log($event['id'] . ' ' . $event['type']);توفر حزمة SDK أيضا sf.webhooks.verifySignature(rawBody, header, secret) التي تعيد true أو false بدل رمي خطأ. وتقبل الدالتان خيارا اختياريا { toleranceSec }.
اختبار webhooks على جهازك
Section titled “اختبار webhooks على جهازك”تحتاج نقطة النهاية إلى عنوان HTTPS عام، وهو ما لا يملكه حاسوبك المحمول. أثناء التطوير شغّل smsfabric listen بدلا من ذلك. يفتح اتصالا واحدا من جهازك إلى SMSFabric ويرسل كل حدث إلى خادمك المحلي، موقعا بترويستي SMSFabric-Signature وSMSFabric-Event-Id نفسيهما. فتعمل شيفرة التحقق لديك دون تغيير.
export SMSFABRIC_WEBHOOK_SECRET="whsec_…" # the secret your handler verifies withsmsfabric listen --forward-to http://localhost:3000/hooks/smsلا يعيد listen إرسال الأحداث التي فاتته ولا يعيد محاولة الإرسال الفاشل، فاستخدمه للتطوير فقط. ولبناء الشيء نفسه في أدواتك استخدم sms.webhooks.listen() أو GET /v1/webhooks/listen.
إعادة المحاولة
Section titled “إعادة المحاولة”ينجح الإرسال عندما ترد نقطة النهاية بـ 2xx خلال 10 ثوان. أي شيء آخر (حالة أخرى، أو انتهاء المهلة، أو رفض الاتصال) تُعاد محاولته بفواصل متزايدة. لا تُتبع عمليات إعادة التوجيه.
| المحاولة | التأخير بعد المحاولة السابقة |
|---|---|
| 1 | فورا |
| 2 | دقيقة واحدة |
| 3 | 5 دقائق |
| 4 | 15 دقيقة |
| 5 | ساعة واحدة |
| 6 | 3 ساعات |
| 7 | 6 ساعات |
| 8 | 13 ساعة |
بعد المحاولة الثامنة، أي بعد نحو 23.5 ساعة من الحدث، يُعلَّم الإرسال failed. الإرسال إلى نقطة نهاية معطلة يفشل دون أن يُرسل.
التعامل مع التكرار والترتيب
Section titled “التعامل مع التكرار والترتيب”بسبب إعادة المحاولة وإعادة الإرسال قد يصلك الحدث نفسه أكثر من مرة. أزل التكرار بالاعتماد على SMSFabric-Event-Id (القيمة نفسها لـ id في المحتوى): احفظ المعرّفات التي عالجتها وتخطّ ما رأيته.
// A unique index on processed_events.id makes this safe with several workers.const inserted = await db.query('INSERT INTO processed_events (id) VALUES ($1) ON CONFLICT DO NOTHING', [eventId]);if (inserted.rowCount === 0) return; // already handledقد تصل الأحداث أيضا بغير ترتيبها: قد يسبق message.delivered حدث message.sent متأخرا. قارن status للرسالة بما حفظته، ولا تُرجعها إلى الوراء أبدا. الحالات تتقدم فقط: queued ثم routed ثم sending ثم sent، ثم إحدى delivered أو failed أو blocked.
إعادة إرسال طلب
Section titled “إعادة إرسال طلب”إذا تعطلت نقطة النهاية أو كان فيها خطأ، أعد إرسال الطلبات بعد الإصلاح:
- من البوابة: المطوّرون ← Webhooks، افتح نقطة النهاية واضغط إعادة الإرسال على الطلب. انظر Webhooks في البوابة.
- من الواجهة البرمجية: اعرض المحاولات عبر
GET /v1/webhooks/:id/deliveries، ثمPOST /v1/webhooks/:id/deliveries/:deliveryId/replay.
إعادة الإرسال ترسل الحدث نفسه بالمعرّف id نفسه، موقّعا بوقت جديد. إذا كنت عالجته من قبل فسيتعرف عليه منطق إزالة التكرار لديك.
curl -X POST https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/deliveries/dlv_f3i6l9o2r5u8x1a4d7g0j3m6/replay \ -H "X-Api-Key: $SMSFABRIC_API_KEY"استقبال الأحداث على جهازك
Section titled “استقبال الأحداث على جهازك”أثناء بناء معالج webhook لا يملك حاسوبك عنوان https عاما يستدعيه SMSFabric. يحل بث الاستماع هذه المشكلة: يفتح جهازك اتصالا صادرا واحدا ويستقبل عبره أحداث المؤسسة، دون نفق.
مع سطر الأوامر، مرر كل حدث إلى المعالج المحلي، موقّعا تماما مثل التسليم الحقيقي:
export SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxexport SMSFABRIC_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxsmsfabric listen --forward-to http://localhost:3000/hooks/smsfabricيتحقق معالجك من الترويسة SMSFabric-Signature باستخدام SMSFABRIC_WEBHOOK_SECRET، فيعمل الكود أعلاه دون تغيير. وإن لم تضبط هذا المتغير، ينشئ سطر الأوامر سرا لهذا التشغيل ويطبعه مرة واحدة.
في Node، اقرأ البث نفسه بالدالة webhooks.listen() من الحزمة:
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const stop = new AbortController();process.once('SIGINT', () => stop.abort());
for await (const event of sms.webhooks.listen({ events: ['message.delivered', 'message.failed'], signal: stop.signal })) { console.log(event.type, event.id, event.payload.data);}يحتاج المفتاح webhooks:manage. وصف البث نفسه في مرجع الواجهة البرمجية.
قائمة التحقق
Section titled “قائمة التحقق”- رد بـ
2xxبسرعة، ثم نفذ العمل في طابور. - تحقق من التوقيع على المحتوى الخام، بهامش 300 ثانية.
- أزل التكرار بالاعتماد على
SMSFabric-Event-Id. - احفظ سر التوقيع في مخزن أسرار. لتغييره، أنشئ نقطة نهاية جديدة وانشر سرها، ثم احذف القديمة.
- راقب الطلبات الفاشلة في البوابة، وأعد إرسالها بعد أي انقطاع.