روابط الويب
اشترك في أنظمتك الخاصة لتلقي أحداث Flash. سجّل نقطة نهاية HTTPS للأحداث التي تهمك، وسيقوم Flash بتسليم حمولة بيانات صغيرة وموقّعة فور وقوع كل حدث — بدون استقصاء، ولا تصدير ليلي. تتبع التوقيعات مواصفات خطافات الويب القياسية، وتُعاد محاولات التسليم مع فترة تأخير، ويتم تسجيل كل محاولة.
تسجيل نقطة نهاية
أنشئ نقطة نهاية webhook بمفتاح Bearer fl_live_ يحتوي على نطاق webhooks:manage. أرسل طلب HTTPS url وقائمة eventTypes التي ترغب في إرسالها. يُعاد سر التوقيع في الاستجابة ولن يُعاد إرساله مرة أخرى - لذا احفظه بأمان؛ فأنت بحاجة إليه للتحقق من كل عملية إرسال.
curl -X POST https://flash.socialhub.ai/api/v2/webhooks \
-H "Authorization: Bearer fl_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.your-app.com/flash",
"description": "prod ingest",
"eventTypes": ["member.created", "loyalty.tier_upgraded"]
}'
# 201 Created
# {
# "data": {
# "id": "whe_...",
# "url": "https://hooks.your-app.com/flash",
# "eventTypes": ["member.created", "loyalty.tier_upgraded"],
# "status": "active",
# "secret": "whsec_..." <-- shown ONCE, store it now
# }
# }إدارة نقاط النهاية لاحقًا باستخدام GET /api/v2/webhooks (قائمة، بدون أسرار)، PATCH /api/v2/webhooks/{id} (تغيير عنوان URL / الأحداث / الحالة، أو إرسال { "action": "rotate_secret" } لتغيير السر)، وDELETE /api/v2/webhooks/{id}. يمكنك أيضًا تسجيل عمليات التسليم واختبارها وإعادة تشغيلها من الإعدادات ← Webhooks.
كتالوج الفعاليات
اسأل API عن الأحداث التي يُمكنك الاشتراك فيها. يُستمدّ هذا الكتالوج من مصدر موثوق لتفعيل الأتمتة المباشرة، لذا فهو يسرد أحداث فقط التي تُفعّل اليوم - مُصنّفة حسب مرحلة دورة حياة العميل (الاستحواذ، التفاعل، الولاء، الاحتفاظ، التجارة، الترويج) - مع مفتاح الحدث ووصفه ومثال على حمولته. كما توثّق الاستجابة غلاف الحمولة المشتركة وعناوين التوقيع.
curl https://flash.socialhub.ai/api/v2/events/catalog \
-H "Authorization: Bearer fl_live_..."
# { "data": { "events": [
# { "event": "member.created", "label": "Member created",
# "stage": "acquisition", "examplePayload": { ... } },
# { "event": "loyalty.tier_upgraded", "label": "Tier upgraded",
# "stage": "loyalty", "examplePayload": { ... } },
# ...
# ],
# "payload": { "schema": { ... }, "headers": { ... } }
# } }ضع مفتاح event الخاص بالحدث مباشرةً في eventTypes array عند الاشتراك. يتطلب ذلك نطاق webhooks:manage.
حمولة بيانات صغيرة الحجم، لا تحتوي على معلومات شخصية حساسة
تحتوي كل عملية تسليم على نفس الحزمة الصغيرة: ملف ثابت id، وملف الحدث type، وملف created_at timestamp، وكتلة مضغوطة data. لا تحتوي الحمولة مطلقًا على بيانات شخصية - لا بريد إلكتروني، ولا اسم، ولا رقم هاتف، ولا عنوان. عندما تحتاج إلى تفاصيل العضو، استرجعها عبر API الموثق باستخدام member_ref. هذا يحافظ على معلومات التعريف الشخصية في سجل العضو ويمنعها من الوصول إلى سجلات الويب هوك.
POST https://hooks.your-app.com/flash
webhook-id: evt_a1b2c3... # stable across retries — dedupe on this
webhook-timestamp: 1767225600 # unix seconds
webhook-signature: v1,K5x0mF...== # base64 HMAC-SHA256 (may be space-separated during rotation)
Content-Type: application/json
{
"id": "evt_a1b2c3...",
"type": "loyalty.tier_upgraded",
"created_at": "2026-01-01T00:00:00.000Z",
"data": {
"resource_id": "mbr_...",
"member_ref": "mbr_...", // opaque member id — fetch PII via the API
"tier": "Gold", // present on loyalty / tier events
"amount_band": "100-500" // coarse band on commerce events — never the exact amount
}
}التحقق من كل توقيع
Flash يوقع على كل عملية تسليم باستخدام نقطة النهاية الخاصة بك whsec_ استخدام المفتاح روابط الويب القياسية (HMAC-SHA256)أعد حساب التوقيع على {webhook-id}.{webhook-timestamp}.{body} وقارنها، في زمن ثابت، مع webhook-signature العنوان. ارفض أي شيء لا يتطابق، وارفض a webhook-timestamp هذا قديم جدًا بحيث لا يمكن الدفاع عنه ضد عمليات إعادة التشغيل. مفتاح التوقيع هو بايتات السر بعد فك تشفيرها باستخدام Base64. whsec_ البادئة، وفقًا للمواصفات. أثناء عملية التدوير السرية، يحمل رأس الصفحة عدة مفصولة بمسافات. v1,… القيم — اقبل التسليم إذا أي مباراة.
import crypto from "node:crypto";
// req.body must be the RAW, unparsed request body string.
function verifyFlashWebhook(headers, rawBody, whsec) {
const id = headers["webhook-id"];
const ts = headers["webhook-timestamp"];
const sigHeader = headers["webhook-signature"]; // "v1,<b64> v1,<b64> ..."
// reject stale deliveries (5 min tolerance)
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(whsec.replace(/^whsec_/, ""), "base64");
const expected = crypto
.createHmac("sha256", key)
.update(`${id}.${ts}.${rawBody}`)
.digest("base64");
return sigHeader
.split(" ")
.map((p) => p.split(",")[1])
.some((sig) =>
sig &&
sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
);
}إعادة المحاولات، والتكرار، وسجل التسليم
إرجاع 2xx بسرعة
استقبل أي 2xx وقم بتنفيذ عملك بشكل غير متزامن. يتم التعامل مع 429 أو 5xx أو انتهاء المهلة أو خطأ الاتصال على أنها قابلة لإعادة المحاولة.
إعادة المحاولة تلقائيًا مع فترة انتظار
تُعاد محاولات الفشل القابلة لإعادة الاتصال مع تأخير أسي كامل. يُعامل الخطأ 3xx أو الخطأ 4xx غير 429 كفشل دائم ولا يُعاد الاتصال به.
إزالة التكرارات بواسطة webhook-id
يبقى id ثابتًا في جميع المحاولات، لذا فإن التسليم لمرة واحدة على الأقل آمن: تعامل مع webhook-id المتكرر كما لو أنه قد تم التعامل معه بالفعل.
سجل التسليم وإعادة التشغيل
يتم تسجيل كل محاولة. إذا استُنفدت محاولات إعادة الإرسال، تُعتبر عملية التسليم فاشلة؛ يمكنك معاينة عمليات التسليم وإعادة تشغيلها من الإعدادات ← Webhooks.