ابنِ تكاملات Webhook موثوقة وفق العقود التي يقدّمها RawNak فعلياً.

البدء السريع

أنشئ مساحة عمل، انسخ رابط الشركة، أرسل طلب JSON، ثم راجع الحدث ومحاولة التسليم في اللوحة.

• أنشئ حساباً من زر بدء التجربة المجانية.
• أنشئ وجهة أو اختر وجهة موجودة في اللوحة.
• أرسل طلب POST إلى /webhook/<company>.
• افتح Deliveries لمراجعة الحالة ورمز الاستجابة والتأخير والمحاولات وإجراءات Replay.

curl -X POST "https://api.rawnakwebhook.com/webhook/<company>" \
  -H "Content-Type: application/json" \
  -d '{"event":"order.created","id":"evt_123"}'

المصادقة والأسرار

تتطلب APIs الخاصة باللوحة توكن Bearer صادر عن مسار المصادقة. ويستخدم توقيع Webhook سر مساحة العمل مع الترويسة X-Rawnak-Signature.

• احتفظ بسر التوقيع على الخادم فقط.
• استخدم Security لتدوير سر التوقيع الوارد.
• يوجد مسار كشف أولي لمرة واحدة في POST /api/security/reveal-initial-secret.
• توكن اللوحة منفصل عن سر توقيع Webhook.

استقبال Webhooks

مسار الاستقبال العام هو POST /webhook/<company>. يطبّق Flask حد MAX_CONTENT_LENGTH، وقيمته الافتراضية 1,048,576 بايت.

• يُستخدم جسم الطلب الخام للتوقيع ولحفظ Payload الحدث.
• تستخدم أمثلة المنتج Content-Type: application/json.
• القبول الناجح يعيد HTTP 200. وتُرفض الحالات غير المسموحة قبل INSERT.
• يمثل الجزء بعد /webhook/ معرّف الشركة.

الوجهات وإعادة التوجيه

تتضمن الوجهة URL وسرّاً وtimeout_seconds وmax_attempts وفلاتر الأحداث وضوابط السرعة والتزامن الاختيارية.

• تبدأ المحاولة الآلية من 1 وتدعم حتى 3 محاولات.
• تأخيرات إعادة المحاولة هي 180 ثانية ثم 360 ثانية.
• يُقيّد timeout بين 3 و15 ثانية، وتستخدم الطلبات الخارجية طبقة HTTP الآمنة دون Redirects.
• تشمل الاستجابات القابلة لإعادة المحاولة 408 و425 و429 و500 و502 و503 و504.
• Replay تشغيل تسليم جديد، أما Retry delivery فيتابع محاولة مؤهلة بحالة retrying.

curl -X POST "https://api.rawnakwebhook.com/webhook/<company>" \
  -H "Content-Type: application/json" \
  -d '{"event":"order.created","id":"evt_123"}'

import crypto from "node:crypto";
const signature = crypto.createHmac("sha256", process.env.RAWNAK_SECRET)
  .update(rawBody).digest("hex");
// Send: X-Rawnak-Signature: sha256=<signature>

import hashlib, hmac
signature = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
headers = {"X-Rawnak-Signature": f"sha256={signature}"}

$signature = hash_hmac('sha256', $rawBody, $secret);
$headers = ['X-Rawnak-Signature: sha256=' . $signature];

التحقق من التوقيع

يوقّع RawNak جسم الطلب حرفياً باستخدام HMAC-SHA256، وتُرسل النتيجة في X-Rawnak-Signature مع البادئة sha256=.

• اقرأ البايتات الخام قبل تحليل JSON.
• احسب HMAC-SHA256 باستخدام سر مساحة العمل.
• قارن البصمة بمقارنة ثابتة الزمن.
• ارفض الترويسة المفقودة أو غير المطابقة.

import crypto from "node:crypto";
const signature = crypto.createHmac("sha256", process.env.RAWNAK_SECRET)
  .update(rawBody).digest("hex");
// Send: X-Rawnak-Signature: sha256=<signature>

import hashlib, hmac
signature = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
headers = {"X-Rawnak-Signature": f"sha256={signature}"}

$signature = hash_hmac('sha256', $rawBody, $secret);
$headers = ['X-Rawnak-Signature: sha256=' . $signature];

الباقات والحدود

القيم التالية مأخوذة من PLAN_LIMITS وخرائط الميزات في webhook_server.py.

• التجربة المجانية: وجهة واحدة، 1,000 حدث شهرياً، 5 أحداث/ثانية، طلب متزامن واحد.
• Starter: 3 وجهات، 10,000 حدث شهرياً، 5 أحداث/ثانية، طلب متزامن واحد.
• Growth: 10 وجهات، 100,000 حدث شهرياً، 100 حدث/ثانية، 10 طلبات متزامنة.
• Enterprise: 50 وجهة، 1,000,000 حدث شهرياً، 1,000 حدث/ثانية، 20 طلباً متزامناً.
• الاحتفاظ مضبوط لكل مساحة عمل بين 1 و3,650 يوماً، والافتراضي التجربة 7 أيام، Starter 30 يوماً، Growth 90 يوماً، Enterprise 180 يوماً.

مرجع الأخطاء

تعيد API أخطاء بصيغة JSON، وقد تختلف الرسالة حسب التحقق وحالة دورة حياة الشركة.

• 400 — إدخال غير صالح أو توقيع/طلب غير صالح.
• 401 — مصادقة مفقودة أو منتهية أو غير صحيحة.
• 402 — يلزم إجراء فوترة أو دورة حياة مناسبة.
• 403 — لا توجد صلاحية الشركة أو الأدمن المطلوبة.
• 404 — المسار أو المورد غير موجود.
• 409 — تعارض في الحالة أو إجراء مكرر.
• 429 — تجاوز معدل الطلب؛ أعد المحاولة بعد مهلة Retry-After.
• 500/503 — مشكلة مؤقتة في الخادم؛ أعد المحاولة لاحقاً أو تواصل مع [email protected].

أفضل ممارسات الأمان

تعامل مع أسرار Webhook وتوكنات اللوحة وبيانات الوجهات كأسرار خادمية.

• تحقق من X-Rawnak-Signature على البايتات الخام.
• استخدم HTTPS للوجهات.
• دوّر الأسرار عند احتمال انكشافها.
• لا تسجل Authorization أو Cookies أو الأسرار.

الأسئلة الشائعة

تستمر التجربة المجانية 7 أيام. وتُفرض حدود الباقات ودورة الحياة في Backend وليس في المتصفح.

سجل التغييرات

يضيف Release 4-1 صفحة توثيق المطورين وتجهيز SEO التقني، دون تغيير سلوك API الحالي.