تخطَّ إلى المحتوى

Webhooks

الـ webhook نقطة نهاية HTTPS على خادمك تستدعيها SMSFabric عند حدوث شيء: تسليم رسالة، أو وصول SMS، أو انقطاع هاتف. تغنيك webhooks عن الاستعلام المتكرر، وهي الطريقة الوحيدة لمعرفة أحداث لم تبدأها أنت، كالرسائل الواردة.

  1. أنشئ مسارا يقبل POST بمحتوى JSON ويرد بـ 2xx خلال 10 ثوان. أجّل العمل البطيء إلى ما بعد الرد، في طابور.
  2. سجّله من المطوّرون ← Webhooks في البوابة (شرح خطوة بخطوة)، أو عبر POST /v1/webhooks. يحتاج المفتاح إلى webhooks:manage.
  3. احفظ signingSecret من الاستجابة. يبدأ بـ whsec_ ولا يظهر إلا مرة واحدة.
  4. أرسل حدثا تجريبيا عبر 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، عند الحفظ وعند كل إرسال.

الحدث يُرسل عندما 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].

كل إرسال طلب POST مع Content-Type: application/json:

POST /hooks/smsfabric HTTP/1.1
Content-Type: application/json
User-Agent: SMSFabric-Webhooks/1.0
SMSFabric-Signature: t=1795086909,v1=5f0c3a8e9b1d4c7e2a6f8b0d3e5c7a9f1b3d5e7f9a1c3e5b7d9f1a3c5e7b9d1f
SMSFabric-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 الكائن الذي يخصه الحدث.

يستطيع أي أحد إرسال طلب إلى رابط عام. قبل أن تتصرف بناء على طلب، تأكد أن SMSFabric أرسلته وأنه لم يُعد إرساله لاحقا.

الترويسة SMSFabric-Signature بالشكل t=<unix seconds>,v1=<hex>، حيث v1 هو HMAC-SHA256 للنص <t>.<raw body> بمفتاح سر التوقيع الخاص بك. للتحقق:

  1. اقرأ محتوى الطلب الخام كما وصل تماما. تحليل JSON ثم إعادة تسلسله يغير البايتات ويفسد التوقيع.
  2. قسّم الترويسة عند , وخذ t وكل قيم v1.
  3. ارفض الطلب إذا ابتعد t أكثر من 300 ثانية عن ساعتك.
  4. احسب HMAC-SHA256(secret, t + "." + rawBody) بصيغة hex وقارنه بـ v1 مقارنة في زمن ثابت.
  5. رد بـ 400 (أو 401) إذا لم يتطابق، ولا تعالج الحدث.

كل إعادة محاولة تُوقّع من جديد بقيمة t جديدة، فتجتاز المحاولة المتأخرة نافذة الـ 300 ثانية.

webhook.ts
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);

توفر حزمة SDK أيضا sf.webhooks.verifySignature(rawBody, header, secret) التي تعيد true أو false بدل رمي خطأ. وتقبل الدالتان خيارا اختياريا { toleranceSec }.

تحتاج نقطة النهاية إلى عنوان HTTPS عام، وهو ما لا يملكه حاسوبك المحمول. أثناء التطوير شغّل smsfabric listen بدلا من ذلك. يفتح اتصالا واحدا من جهازك إلى SMSFabric ويرسل كل حدث إلى خادمك المحلي، موقعا بترويستي SMSFabric-Signature وSMSFabric-Event-Id نفسيهما. فتعمل شيفرة التحقق لديك دون تغيير.

نافذة طرفيّة
export SMSFABRIC_WEBHOOK_SECRET="whsec_…" # the secret your handler verifies with
smsfabric listen --forward-to http://localhost:3000/hooks/sms

لا يعيد listen إرسال الأحداث التي فاتته ولا يعيد محاولة الإرسال الفاشل، فاستخدمه للتطوير فقط. ولبناء الشيء نفسه في أدواتك استخدم sms.webhooks.listen() أو GET /v1/webhooks/listen.

ينجح الإرسال عندما ترد نقطة النهاية بـ 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.

إذا تعطلت نقطة النهاية أو كان فيها خطأ، أعد إرسال الطلبات بعد الإصلاح:

  • من البوابة: المطوّرون ← 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export SMSFABRIC_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
smsfabric listen --forward-to http://localhost:3000/hooks/smsfabric

يتحقق معالجك من الترويسة SMSFabric-Signature باستخدام SMSFABRIC_WEBHOOK_SECRET، فيعمل الكود أعلاه دون تغيير. وإن لم تضبط هذا المتغير، ينشئ سطر الأوامر سرا لهذا التشغيل ويطبعه مرة واحدة.

في Node، اقرأ البث نفسه بالدالة webhooks.listen() من الحزمة:

listen.ts
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. وصف البث نفسه في مرجع الواجهة البرمجية.

  • رد بـ 2xx بسرعة، ثم نفذ العمل في طابور.
  • تحقق من التوقيع على المحتوى الخام، بهامش 300 ثانية.
  • أزل التكرار بالاعتماد على SMSFabric-Event-Id.
  • احفظ سر التوقيع في مخزن أسرار. لتغييره، أنشئ نقطة نهاية جديدة وانشر سرها، ثم احذف القديمة.
  • راقب الطلبات الفاشلة في البوابة، وأعد إرسالها بعد أي انقطاع.