- نطاقات قابلة للتهيئة لتغطية بيانات التقويم (calendar) والإشارات (signals) بحيث تستلم فقط البيانات التي تحتاجها
- عمليات تسليم متطابقة (idempotent) مع ترويسة فريدة
X-BZ-Deliveryوحقلidفي الحمولة لأغراض إزالة التكرار - جدول إعادة محاولة متين يتدرج من محاولات سريعة بأسلوب أسي إلى محاولات طويلة الأمد تُجرى كل ساعة
- تحويلات اختيارية على
contentلمواءمة الحمولات مع توقعات الأنظمة اللاحقة في سلسلة المعالجة
- Method:
POST - Content-Type:
application/json - User-Agent:
Benzinga-Dispatch/v1.0.0 {build-version} - Custom Header:
X-BZ-Delivery- معرّف UUID فريد خاص بكل محاولة تسليم (مفيد لمنع التكرار)
- المرحلة الأسية: 15 محاولة خلال أول 5 دقائق
- محاولات أسية إضافية: 11 محاولة إضافية عند الحاجة
- مرحلة الفاصل الزمني الثابت: 12 محاولة في الساعة × 24 ساعة/يوم × 7 أيام (لإعادة المحاولة على المدى الطويل)
- أقصى مدة انتظار: 5 دقائق بين المحاولات في المرحلة الأسية
- مهلة الطلب: 30 ثانية لكل طلب
- رموز النجاح (200-202، 204): تشير إلى نجاح عملية التسليم. لن تتم أي محاولات إعادة إرسال.
- رموز أخطاء العميل (401-403): تشير إلى فشل في المصادقة/التفويض. سيتم إيقاف محاولات إعادة الإرسال فورًا لمنع المزيد من المحاولات الفاشلة.
- رموز أخرى (4xx، 5xx): ستؤدي إلى محاولات إعادة إرسال وفقًا لسياسة إعادة المحاولة أعلاه.
id(string, UUID): معرّف فريد لتسليم الـ webhook هذا. استخدمه لمنع التكرار.api_version(string): معرّف إصدار واجهة برمجة التطبيقات API. حاليًا"webhook/v1".kind(string): معرّف مسار نوع البيانات. راجع أنواع البيانات المدعومة لجميع القيم المحتملة.
action(string): نوع إجراء الحدث. القيم الممكنة:"Created": تم إنشاء بيانات جديدة (القيمة الافتراضية لمفاتيح webhook الجديدة)"Updated": تم تحديث البيانات الحالية"Removed": تم حذف البيانات- ملاحظة: قد تتلقى مفاتيح webhook القديمة قيماً بحروف صغيرة:
"created","updated","removed"
id(string): معرّف فريد لسجل calendar/signaltimestamp(string، ISO 8601): الطابع الزمني عند إنشاء الـ webhookcontent(object): بيانات calendar أو signal الفعلية. تختلف البنية حسب نوع البيانات (انظر أنواع البيانات المدعومة)
- Created: يتم إرسال حدث عند نشر بيانات
calendarأو بيانات الإشارات الجديدة - Updated: يتم إرسال حدث عند تعديل البيانات الحالية
- Removed: يتم إرسال حدث عند حذف البيانات
- مفاتيح webhook الجديدة: تستقبل إجراءات بحروف كبيرة (
"Created","Updated","Removed") - مفاتيح webhook القديمة (Legacy): تستقبل إجراءات بحروف صغيرة (
"created","updated","removed")
- أنواع البيانات: التصفية حسب أنواع معيّنة من
calendar/الإشارات (مثلًا: الأرباح فقط، التقييمات فقط) - عوامل التصفية الجغرافية: التحكم في ما إذا كنت ستستقبل:
- بيانات السوق الأمريكية (
AllowUSA) - بيانات السوق الكندية (
AllowCanada) - بيانات السوق الهندية (
AllowIndia) - لبيانات WIIMs
- بيانات السوق الأمريكية (
- عامل تصفية التاريخ: استبعاد البيانات التاريخية الأقدم من تاريخ معيّن (
MaxHistoricalDate)
- البورصات الأمريكية: NYSE, NASDAQ, AMEX, ARCA, OTC, OTCBB, PINX, PINK, BATS, IEX
- البورصات الكندية: TSX, TSXV, CSE, CNSX
- إعادة تسمية الحقول
- تحويل تنسيقات البيانات
- تصفية/إزالة الحقول
id (UUID) في الـ payload لتطبيق خاصية idempotency. خزّن معرّفات التسليم التي جرى معالجتها لتفادي المعالجة المكرّرة.
- أرجِع
200 OKأو204 No Contentعلى الفور عند استلام الـ webhook - عالِج البيانات بشكل غير متزامن إذا لزم الأمر
- لا تنفِّذ عمليات طويلة الأمد قبل إرسال الاستجابة
- أرجِع رموز حالة HTTP المناسبة
- في حالة أخطاء المصادقة (401-403)، تأكّد من ضبط الـ endpoint بشكل صحيح
- في حالة الإخفاقات المؤقتة، أرجِع رموز حالة من نوع 5xx لتفعيل إعادة المحاولة
- استخدم HTTPS لنقطة النهاية الخاصة بالـ webhook
- نفِّذ آليات المصادقة/التفويض (مفاتيح واجهة برمجة التطبيقات API، رموز الوصول، إلخ)
- تحقَّق من الترويسة
X-BZ-Deliveryلمزيد من الأمان
- راقب أزمنة استجابة نقطة النهاية الخاصة بك
- اضبط تنبيهات لحالات الفشل المتكررة
- تتبّع ترويسة
X-BZ-Deliveryلتحديد محاولات التسليم
- تحقق من حقل
kindلتحديد نوع البيانات - حلّل كائن
contentوفقًا لبنية نوع البيانات - تعامل مع تنسيقات الإجراء المختلفة (أحرف كبيرة مقابل أحرف صغيرة) إذا كنت بحاجة إلى دعم المفاتيح القديمة
-
عدم استلام أي webhooks
- تحقَّق من أن عنوان الـ webhook (URL) مكوَّن بشكل صحيح
- تأكَّد من أن نقطة النهاية لديك متاحة للعامة
- تأكَّد من أن مفتاح واجهة برمجة التطبيقات API لديك صالح وفعّال
- تحقَّق من أن عوامل التصفية لا تستبعد جميع أنواع البيانات
- تحقَّق من أن عوامل التصفية الجغرافية تطابق البيانات التي تتوقعها
-
عمليات تسليم مكررة
- نفِّذ خاصية idempotency باستخدام الحقل
id - تحقَّق من أزمنة استجابة نقطة النهاية لديك (قد تؤدي الاستجابات البطيئة إلى إعادة المحاولة)
- نفِّذ خاصية idempotency باستخدام الحقل
-
أخطاء مصادقة (401-403)
- تحقَّق من إعدادات المصادقة لنقطة النهاية لديك
- تحقَّق من مفاتيح واجهة برمجة التطبيقات API ورموز الوصول
- ملاحظة: تؤدي أخطاء المصادقة إلى إيقاف إعادة المحاولة فورًا
-
أخطاء انتهاء المهلة
- تأكَّد من أن نقطة النهاية لديك تستجيب خلال 30 ثانية
- عالج البيانات بشكل غير متزامن عند الحاجة
- أعد استجابة نجاح فورًا ثم عالج البيانات لاحقًا
-
تنسيق إجراء غير متوقَّع
- تحقَّق مما إذا كنت تستخدم مفتاح webhook قديمًا (قِيَم الحقل
actionبحروف صغيرة) - حدِّث إلى مفتاح webhook جديد لاستلام قِيَم الحقل
actionبحروف كبيرة - عالِج كلا التنسيقين إذا كنت تدعم عدة عملاء
- تحقَّق مما إذا كنت تستخدم مفتاح webhook قديمًا (قِيَم الحقل
-
أنواع بيانات مفقودة
- تحقَّق من أن تكوين webhook لديك يتضمّن أنواع البيانات المطلوبة
- تحقَّق من عوامل التصفية الجغرافية (إعدادات US/Canada/India)
- تأكَّد من أن عوامل تصفية التاريخ لا تستبعد البيانات الحديثة
- اطّلع على وثائق واجهة برمجة التطبيقات API الخاصة بـ Benzinga
- تواصل مع ممثل حسابك في Benzinga
- راجع إعدادات الـwebhook مع فريق التكامل لديك
- v1.0.0: الإصدار الأولي لخدمة Webhook للبيانات
- Current: الإصدار الحالي مع تحسين آليات التصفية والتحويل وإعادة المحاولة