خطافات الويب
يسجّل sms.webhooks نقاط HTTPS التي تستدعيها SMSFabric عند وقوع حدث، ويعرض محاولات التسليم إليها، ويتحقق من توقيع الأحداث التي يستقبلها خادمك. إدارة النقاط تحتاج إلى النطاق webhooks:manage. الأحداث ومحتواها وإعادة المحاولة موصوفة في دليل خطافات الويب.
| الدالة | طلب HTTP | القيمة المعادة |
|---|---|---|
list() |
GET /v1/webhooks |
Webhook[] |
create(params, options?) |
POST /v1/webhooks |
CreatedWebhook |
update(id, params) |
PATCH /v1/webhooks/:id |
Webhook |
delete(id) |
DELETE /v1/webhooks/:id |
void |
deliveries(id, params?) |
GET /v1/webhooks/:id/deliveries |
Paginated<WebhookDelivery> |
deliveriesAll(id, params?) |
GET /v1/webhooks/:id/deliveries (كل الصفحات) |
AsyncGenerator<WebhookDelivery> |
replay(id, deliveryId) |
POST /v1/webhooks/:id/deliveries/:deliveryId/replay |
WebhookDelivery |
test(id) |
POST /v1/webhooks/:id/test |
WebhookDelivery |
listen(options?) |
GET /v1/webhooks/listen |
AsyncGenerator<ListenedEvent> |
verifySignature(rawBody, header, secret, options?) |
لا يوجد (محلي) | boolean |
constructEvent(rawBody, header, secret, options?) |
لا يوجد (محلي) | WebhookPayload |
listen(options?) |
GET /v1/webhooks/listen (بث) |
AsyncGenerator<ListenedEvent> |
الدالتان verifySignature وconstructEvent مصدّرتان أيضًا وحدهما: import { verifySignature, constructEvent } from '@smsfabric/sdk'. لا تحتاجان إلى عميل ولا إلى مفتاح API، فلا يلزم مستقبل خطافات الويب أن يحمل مفتاحًا. وsms.webhooks.verifySignature وsms.webhooks.constructEvent تستدعيان الدالتين نفسيهما.
كل نقاط الاستقبال في مؤسستك. لا يظهر سر التوقيع فيها أبدًا.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for (const w of await sms.webhooks.list()) console.log(w.id, w.url, w.enabled, w.events.join(', '));create
Section titled “create”تسجّل نقطة استقبال لقائمة من الأحداث events. يجب أن يكون العنوان https في بيئة الإنتاج، وترفض SMSFabric أي مضيف يشير إلى عناوين خاصة أو محلية. تحتوي النتيجة على signingSecret (whsec_…)، ولا يعاد إلا هذه المرة: احفظه في مدير الأسرار.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const webhook = await sms.webhooks.create({ url: 'https://acme.example/hooks/smsfabric', events: ['message.delivered', 'message.failed', 'message.received'], description: 'Order notifications',});console.log(webhook.id);// Save webhook.signingSecret now: it is not shown again.update
Section titled “update”تغيّر url أو events أو enabled أو description. أوقف النقطة بـ enabled: false بدل حذفها أثناء إصلاح خادمك.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.webhooks.update('whk_…', { events: ['message.delivered', 'message.failed', 'campaign.completed'] });await sms.webhooks.update('whk_…', { enabled: false });delete
Section titled “delete”تحذف نقطة الاستقبال، فلا ترسل إليها SMSFabric أحداثًا جديدة.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.webhooks.delete('whk_…');deliveries and deliveriesAll
Section titled “deliveries and deliveriesAll”محاولات التسليم لنقطة واحدة، الأحدث أولًا: نوع الحدث وstatus (pending أو succeeded أو failed) وعدد المحاولات وآخر حالة HTTP وآخر خطأ وموعد المحاولة التالية.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const d of sms.webhooks.deliveriesAll('whk_…')) { if (d.status === 'failed') console.log(d.id, d.eventType, d.lastStatusCode, d.lastError);}replay
Section titled “replay”تضيف الحدث نفسه إلى طابور التسليم لتلك النقطة مرة أخرى، مثلًا بعد إصلاح خلل جعل خادمك يرد بـ 500.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const webhookId = 'whk_…';
for await (const d of sms.webhooks.deliveriesAll(webhookId)) { if (d.status === 'failed') await sms.webhooks.replay(webhookId, d.id);}ترسل حدث webhook.test إلى نقطة الاستقبال، لتتأكد من أن خادمك يستقبله ويتحقق منه.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const delivery = await sms.webhooks.test('whk_…');console.log(delivery.id, delivery.status); // dlv_… pendinglisten
Section titled “listen”تعطيك أحداث خطافات الويب الخاصة بمؤسستك لحظة وقوعها، عبر اتصال صادر واحد، فيستقبلها حاسوب لا يملك رابطا عاما. صُممت للتطوير، وعليها يقوم الأمر smsfabric listen في سطر الأوامر. تحتاج إلى النطاق webhooks:manage.
| الخيار | النوع | ملاحظات |
|---|---|---|
events |
string[] |
أنواع الأحداث المطلوبة، مثل message.delivered. الافتراضي: كل الأحداث. |
signal |
AbortSignal |
ألغه لتتوقف عن الاستماع، فتنتهي الحلقة دون خطأ. |
onStatus |
(status: ListenStatus) => void |
تُستدعى بالقيمة { state: 'connected', listenerId, expiresAt } حين يصبح البث جاهزا، وبالقيمة { state: 'reconnecting', reason, retryInMs } حين ينقطع. |
يحمل كل ListenedEvent الحقول id (معرف الحدث) وtype وpayload (كائن WebhookPayload بعد التحليل) وrawBody، وهو JSON نفسه الذي تستلمه نقطة الاستقبال. لتمرير حدث إلى معالج يتحقق من التواقيع، وقّع rawBody وأرسله كما هو، لا نسخة أعيد تحويلها إلى نص.
import { SMSFabric, SMSFabricError } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
// Stop on Ctrl+C, or after ten minutes.const stop = new AbortController();process.once('SIGINT', () => stop.abort());setTimeout(() => stop.abort(), 10 * 60_000).unref();
try { const events = sms.webhooks.listen({ events: ['message.delivered', 'message.failed', 'message.received'], signal: stop.signal, onStatus: (status) => { if (status.state === 'connected') console.error(`Listening (${status.listenerId})`); else console.error(`Connection lost: ${status.reason}. Retrying in ${status.retryInMs} ms`); }, }); for await (const event of events) { console.log(event.type, event.id, event.payload.data); }} catch (err) { // 400, 401, 403 and 404 end the stream: a bad event type, key or scope. if (err instanceof SMSFabricError) console.error(err.status, err.code, err.detail); else throw err;}تتولى الحزمة دورة حياة البث عنك:
- ينهي الخادم كل بث بعد 5 دقائق. تفتح الحزمة البث التالي حين يرسل القديم
rotate، فلا يضيع حدث عند التبديل، والحدث الذي يظهر في البثين تعطيك إياه مرة واحدة. - بعد انقطاع الاتصال، أو عند
429 too_many_listeners، تعيد الاتصال بانتظار متزايد وتبلغك عبرonStatus. الأحداث التي نُشرت أثناء الانقطاع لا يُعاد إرسالها. - لا تعيد المحاولة عند
400و401و403و404: ترمي الحلقةSMSFabricError.
verifySignature
Section titled “verifySignature”تعيد true عندما تطابق ترويسة SMSFabric-Signature المحتوى الخام للطلب وسر التوقيع. صيغة الترويسة t=<unix seconds>,v1=<hex>، حيث v1 هو HMAC-SHA256 للنص <t>.<raw body>. تجري المقارنة في زمن ثابت، ويفشل التوقيع الأقدم من 300 ثانية، فلا يمكن إعادة إرسال طلب ملتقط لاحقًا.
| الوسيط | النوع | ملاحظات |
|---|---|---|
rawBody |
RawBody (string | Buffer | Uint8Array) |
المحتوى كما وصل تمامًا. تحليل JSON ثم إعادة تسلسله يغير البايتات ويكسر التوقيع. ويعمل Uint8Array الناتج من await request.arrayBuffer() كما هو. |
header |
string | null | undefined |
ترويسة SMSFabric-Signature. غيابها يعيد false. |
secret |
string |
قيمة signingSecret الخاصة بالنقطة. |
options.toleranceSec |
number |
أقصى عمر بالثواني. الافتراضي 300، والقيمة 0 تلغي الفحص. |
options.now |
number |
الوقت الحالي بثواني unix، للاختبارات. |
import { verifySignature } from '@smsfabric/sdk';
const secret = process.env.SMSFABRIC_WEBHOOK_SECRET ?? '';
export function isFromSmsFabric(rawBody: Buffer, signature: string | undefined): boolean { return verifySignature(rawBody, signature, secret);}import { constructEvent, SignatureVerificationError, type RawBody } from '@smsfabric/sdk';
// A Fetch API handler (Next.js route, Hono, Bun, Deno): the body arrives as bytes.export async function POST(request: Request): Promise<Response> { const rawBody: RawBody = new Uint8Array(await request.arrayBuffer()); try { const event = constructEvent(rawBody, request.headers.get('smsfabric-signature'), process.env.SMSFABRIC_WEBHOOK_SECRET ?? ''); console.log(event.id, event.type); return new Response(null, { status: 200 }); } catch (err) { if (err instanceof SignatureVerificationError) return new Response(null, { status: 400 }); throw err; }}لا يستدعي التحقق الواجهة البرمجية ولا يحتاج إلى عميل، لذلك لا يحمل المستقبل أعلاه إلا سر التوقيع. ومع Fetch API يصل المحتوى على شكل بايتات، فمرره بوصفه Uint8Array:
constructEvent
Section titled “constructEvent”تتحقق من التوقيع وتعيد الحدث محللًا { id, type, createdAt, orgId, data }. وترمي SignatureVerificationError إذا كانت الترويسة غائبة أو مشوهة، أو كان التوقيع غير مطابق أو قديمًا، أو كان المحتوى الموقّع ليس كائن JSON. رد حينها بـ 400 ولا تعالج المحتوى.
يستخدم هذا المستقبل node:http فقط. يقرأ المحتوى الخام، ويحده بميغابايت واحد، ويتحقق منه، ويرد بـ 200 فورًا، ثم يعالج الحدث بعد ذلك:
import { createServer, type IncomingMessage } from 'node:http';import { constructEvent, SignatureVerificationError, type WebhookPayload } from '@smsfabric/sdk';
const secret = process.env.SMSFABRIC_WEBHOOK_SECRET ?? '';const MAX_BODY = 1024 * 1024;
async function readRawBody(req: IncomingMessage): Promise<Buffer> { const chunks: Buffer[] = []; let size = 0; for await (const chunk of req) { const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)); size += buf.length; if (size > MAX_BODY) throw new Error('body too large'); chunks.push(buf); } return Buffer.concat(chunks);}
async function handle(event: WebhookPayload): Promise<void> { // Deliveries can repeat: skip an event.id you have already processed. console.log(event.id, event.type, event.data);}
createServer(async (req, res) => { if (req.method !== 'POST' || req.url !== '/hooks/smsfabric') { res.writeHead(404).end(); return; } let event: WebhookPayload; try { const header = req.headers['smsfabric-signature']; event = constructEvent(await readRawBody(req), typeof header === 'string' ? header : undefined, secret); } catch (err) { res.writeHead(err instanceof SignatureVerificationError ? 400 : 413).end(); return; } res.writeHead(200).end(); handle(event).catch((err: unknown) => console.error('webhook handler failed', err));}).listen(3000);مع Express، استخدم express.raw على مسار خطاف الويب ليبقى req.body من نوع Buffer. إذا حلل express.json() العام المحتوى قبل أن يصل إلى معالجك، فلن يطابق التوقيع.
import express from 'express';import { constructEvent, SignatureVerificationError } from '@smsfabric/sdk';
const secret = process.env.SMSFABRIC_WEBHOOK_SECRET ?? '';const app = express();
app.post('/hooks/smsfabric', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => { let event; try { event = constructEvent(req.body, req.header('SMSFabric-Signature'), secret); } catch (err) { if (err instanceof SignatureVerificationError) return res.sendStatus(400); throw err; } res.sendStatus(200); console.log(event.id, event.type);});
app.use(express.json()); // other routes may parse JSON; the webhook route is registered first
app.listen(3000);listen
Section titled “listen”تعيد أحداث webhook الخاصة بالمؤسسة لحظة وقوعها عبر اتصال صادر واحد، فلا يحتاج جهاز التطوير إلى عنوان عام. تحتاج إلى webhooks:manage. الخيارات: events (أنواع الأحداث، والافتراضي كلها) وsignal (للإيقاف) وonStatus (تغيرات الاتصال). يعيد البث الاتصال تلقائيًا، والأحداث التي تقع أثناء الانقطاع لا يعاد إرسالها. في الإنتاج سجّل نقطة نهاية بدلًا منه.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const stop = new AbortController();
for await (const event of sms.webhooks.listen({ events: ['message.delivered', 'message.failed'], signal: stop.signal })) { console.log(event.type, event.id);}قيمة event.rawBody هي نص JSON نفسه الذي تستقبله نقطة النهاية، وevent.payload هي النسخة المحللة منه.