
يتبع تنفيذ الويب هوك لدينا مواصفة Standard Webhooks، مما يضمن التوافق مع أفضل ممارسات الصناعة ومكتبات الويب هوك الموجودة.
الميزات الرئيسية
Real-time Delivery
تلقي إشعارات فورية عند حدوث الأحداث
Secure by Default
تم تضمين التحقق من توقيع HMAC SHA256
Automatic Retries
منطق إعادة محاولة مدمج مع تراجع أسي
Event Filtering
اشترك فقط في الأحداث التي تحتاجها
البدء
Select Events to Receive
اختر الأحداث المحددة التي يجب أن يستمع لها نقطة نهاية الويب هوك عن طريق تحديدها من قائمة الأحداث.
Get Secret Key
احصل على
Secret Key للويب هوك من صفحة الإعدادات. ستستخدمه للتحقق من صحة الويب هوكات المستلمة.تكوين الأحداث المشترك فيها
يمكنك تكوين الأحداث المحددة التي تريد استلامها لكل نقطة نهاية Webhook.الوصول إلى تكوين الأحداث
Navigate to Webhook Details
انتقل إلى لوحة تحكم Dodo Payments الخاصة بك واذهب إلى
Settings > Webhooks.إدارة اشتراكات الأحداث
View Available Events
تعرض الواجهة جميع أحداث الويب هوك المتاحة منظمة في هيكل هرمي. يتم تجميع الأحداث حسب الفئة (على سبيل المثال،
dispute، payment، subscription).Search and Filter
استخدم شريط البحث للعثور بسرعة على أحداث محددة عن طريق كتابة أسماء الأحداث أو الكلمات المفتاحية.
Select Events
حدد المربعات بجانب الأحداث التي تريد تلقيها. يمكنك:
- اختيار الأحداث الفرعية الفردية (على سبيل المثال،
dispute.accepted،dispute.challenged) - اختيار الأحداث الرئيسية لتلقي جميع الأحداث الفرعية المرتبطة بها
- مزج وتنسيق الأحداث المحددة بناءً على احتياجاتك
تسليم Webhook
المهلات
تحتوي Webhooks على نافذة مهلة مدتها 15 ثانية لكل من عمليات الاتصال والقراءة. تأكد من أن نقطة النهاية الخاصة بك تستجيب بسرعة لتجنب المهلات.إعادة المحاولة التلقائية
إذا فشلت عملية تسليم Webhook، فإن مدفوعات Dodo تعيد المحاولة تلقائيًا مع التراجع الأسي لمنع إرهاق نظامك.| المحاولة | التأخير | الوصف |
|---|---|---|
| 1 | على الفور | تحدث المحاولة الأولى على الفور |
| 2 | 5 ثوانٍ | المحاولة الثانية بعد تأخير قصير |
| 3 | 5 دقائق | المحاولة الثالثة مع زيادة التراجع |
| 4 | 30 دقيقة | المحاولة الرابعة مع استمرار التراجع |
| 5 | ساعتان | المحاولة الخامسة مع تأخير ممتد |
| 6 | 5 ساعات | المحاولة السادسة مع تأخير أطول |
| 7 | 10 ساعات | المحاولة السابعة مع أقصى تأخير |
| 8 | 10 ساعات | المحاولة النهائية - يتم وضع علامة على Webhook على أنه فشل إذا لم تنجح |
بحد أقصى 8 محاولات إعادة لكل حدث ويب هوك. على سبيل المثال، إذا فشل ويب هوك ثلاث مرات قبل النجاح، فإن إجمالي وقت التسليم يكون حوالي 35 دقيقة و5 ثوانٍ من المحاولة الأولى.
عدم التكرار
كل حدث ويب هوك يتضمن رأسًا فريدًاwebhook-id. استخدم هذا المعرف لتنفيذ عدم التكرار ومنع المعالجة المكررة.
ترتيب الأحداث
قد تصل أحداث Webhook بترتيب غير صحيح بسبب إعادة المحاولات أو ظروف الشبكة. صمم نظامك للتعامل مع الأحداث بأي تسلسل.ستتلقى أحدث حمولة في وقت التسليم، بغض النظر عن وقت انبعاث حدث الويب هوك في الأصل.
تأمين Webhooks
لضمان أمان Webhooks الخاصة بك، تحقق دائمًا من الحمولة واستخدم HTTPS.التحقق من التوقيعات
كل طلب ويب هوك يتضمن رأسًاwebhook-signature؛ هو توقيع HMAC SHA256 لحمولة الويب هوك والطابع الزمني، موقّع بمفتاحك السري.
التحقق باستخدام SDK (موصى به)
تتضمن جميع SDK الرسمية مساعدات مدمجة للتحقق من صحة Webhooks الواردة وتحليلها بشكل آمن. تتوفر طريقتان:unwrap(): يتحقق من التواقيع باستخدام مفتاح سر الويب هوك الخاص بكunsafe_unwrap(): يفسر الحمولات دون التحقق
التحقق اليدوي (بديل)
إذا لم تكن تستخدم SDK، يمكنك التحقق من التوقيعات بنفسك وفقًا لمواصفات Webhooks القياسية:- قم ببناء الرسالة الموقعة عن طريق ربط
webhook-idوwebhook-timestampوسلسلةpayloadالنصية الخام بالضبط، مفصولة بنقاط (.). - احسب HMAC SHA256 لتلك السلسلة باستخدام مفتاح سر الويب هوك من لوحة التحكم.
- قارن التوقيع المحسوب مع رأس
webhook-signature. إذا تطابقت، فإن الويب هوك أصلي.
نتبع مواصفة Standard Webhooks. يمكنك استخدام مكتباتهم للتحقق من التواقيع: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. بالنسبة لصيغ حمولة الحدث، راجع Webhook Payload.
الرد على Webhooks
- يجب أن يعيد معالج الويب هوك رمز الحالة
2xx status codeللاعتراف باستلام الحدث. - أي استجابة أخرى ستُعامل على أنها فشل، وسيُعاد محاولة الويب هوك.
أفضل الممارسات
Use HTTPS endpoints only
Use HTTPS endpoints only
استخدم دائمًا عناوين URL عبر HTTPS لنقاط نهاية الويب هوك. عناوين HTTP عرضة لهجمات الوسيط وتعرض بيانات الويب هوك.
Respond immediately
Respond immediately
أعد رمز الحالة
200 فور استقبال الويب هوك. قم بمعالجة الحدث بشكل غير متزامن لتجنب نفاد الوقت.Handle duplicate events
Handle duplicate events
نفذ عدم التكرار باستخدام رأس
webhook-id لمعالجة نفس الحدث عدة مرات بأمان دون تأثيرات جانبية.Secure your webhook secret
Secure your webhook secret
خزّن سر الويب هوك بشكل آمن باستخدام متغيرات البيئة أو مدير الأسرار. لا تقم أبدًا بحفظ الأسرار في نظام التحكم بالإصدارات.
هيكل حمولة Webhook
فهم هيكل حمولة Webhook يساعدك على تحليل ومعالجة الأحداث بشكل صحيح.تنسيق الطلب
الرؤوس
معرّف فريد لحدث الويب هوك هذا. استخدمه لفحوصات عدم التكرار.
توقيع HMAC SHA256 للتحقق من صحة الويب هوك.
طابع زمني يونكس (بالثواني) عند إرسال الويب هوك.
جسم الطلب
معرّف عملك في Dodo Payments.
نوع الحدث الذي تسبب في تشغيل هذا الويب هوك (على سبيل المثال،
payment.succeeded، subscription.active).طابع زمني بتنسيق ISO 8601 يوضح وقت حدوث الحدث.
حمولة خاصة بالحدث تحتوي على معلومات مفصلة حول الحدث.
مثال على الحمولة
Event Types
تصفح جميع أنواع أحداث الويب هوك المتاحة
Event Payloads
عرض مخططات الحمولة التفصيلية لكل حدث
اختبار Webhooks
يمكنك اختبار تكامل Webhook الخاص بك مباشرة من لوحة معلومات مدفوعات Dodo للتأكد من أن نقطة النهاية الخاصة بك تعمل بشكل صحيح قبل الانتقال إلى الإنتاج.
الوصول إلى واجهة الاختبار
اختبار Webhook الخاص بك
توفر واجهة الاختبار طريقة شاملة لاختبار نقطة نهاية Webhook الخاصة بك:Select Event Type
استخدم قائمة الاختيار لتحديد نوع الحدث الذي تريد اختباره (على سبيل المثال،
payment.succeeded، payment.failed، إلخ).تحتوي القائمة على جميع أنواع أحداث الويب هوك المتاحة التي يمكن لنقطة النهاية الخاصة بك استقبالها.
Review Schema and Example
تعرض الواجهة كلًا من المخطط (بنية البيانات) ومثال (حمولة نموذجية) لنوع الحدث المحدد.
التحقق من اختبارك
مثال على التنفيذ
إليك تنفيذ كامل باستخدام Express.js يظهر التحقق من Webhook ومعالجته:اختبار الويب هوكات باستخدام واجهة سطر الأوامر
يوفر Dodo Payments CLI أمرين لاختبار الويب هوكات أثناء التطوير المحلي دون الحاجة إلى مغادرة الطرفية.الاستماع إلى الويب هوكات الحية محليًا
قم بتمرير أحداث الويب هوك الحقيقية من حساب وضع الاختبار إلى خادم التطوير المحلي في الوقت الفعلي:http://localhost:3000/webhook)، محافظةً على جميع الرؤوس بما في ذلك رؤوس التوقيع لاختبار التحقق.
يعمل المستمع فقط بمفاتيح API في وضع الاختبار. شغّل
dodo login واختر وضع الاختبار قبل استخدام هذا الأمر.تشغيل أحداث ويب هوك وهمية
أرسل حمولات ويب هوك وهمية إلى أي نقطة نهاية دون إنشاء معاملات حقيقية:CLI Webhook Testing Docs
راجع توثيق اختبار الويب هوك الكامل في CLI
الإعدادات المتقدمة
توفر علامة التبويب الإعدادات المتقدمة خيارات تكوين إضافية لضبط سلوك نقطة نهاية الويب هوك.تحديد معدل (التحكم في التدفق)
تحكم في المعدل الذي تُسلم به أحداث الويب هوك إلى نقطة النهاية لمنع إرهاق نظامك.Configure Rate Limit
انقر على زر Edit لتعديل إعدادات تحديد المعدل.
بشكل افتراضي، يتم تطبيق “بدون حد للمعدل” على الويب هوكات، مما يعني أن الأحداث تُسلم بمجرد حدوثها.
الرؤوس المخصصة
أضف رؤوس HTTP مخصصة إلى جميع طلبات الويب هوك المرسلة إلى نقطة النهاية. هذا مفيد للمصادقة أو التوجيه أو إضافة البيانات الوصفية.التحويلات
تسمح لك التحويلات بتعديل حمولة الويب هوك وإعادة توجيهها إلى عنوان URL مختلف. تتيح لك هذه الميزة القوية ما يلي:- تعديل بنية الحمولة قبل المعالجة
- توجيه الويب هوكات إلى نقاط نهاية مختلفة بناءً على المحتوى
- إضافة أو إزالة حقول من الحمولة
- تحويل تنسيقات البيانات
Configure Transformation
انقر على Edit transformation لتحديد قواعد التحويل الخاصة بك.
يمكنك استخدام JavaScript لتحويل حمولة الويب هوك وتحديد عنوان URL مختلف.
مراقبة سجلات الويب هوك
توفر علامة التبويب السجلات رؤية شاملة لحالة تسليم الويب هوك، مما يتيح لك مراقبة وتصحيح وإدارة الأحداث بفعالية.
مراقبة النشاط
توفر علامة التبويب النشاط رؤى في الوقت الفعلي حول أداء تسليم الويب هوك مع تحليلات مرئية.
تنبيهات البريد الإلكتروني
ابقَ مُطلعًا على حالة الويب هوك لديك مع إشعارات البريد الإلكتروني التلقائية. عند فشل تسليم الويب هوك أو توقف نقطة النهاية عن الاستجابة، ستتلقى تنبيهات بريد إلكتروني حتى تتمكن من معالجة المشاكل بسرعة والحفاظ على تشغيل التكاملات بسلاسة.
تفعيل تنبيهات البريد الإلكتروني
Navigate to Alerting Settings
اذهب إلى لوحة تحكم Dodo Payments الخاصة بك وانتقل إلى Dashboard → Webhooks → Alerting.
Enable Email Notifications
فعّل إشعارات البريد الإلكتروني لبدء تلقي التنبيهات حول مشكلات تسليم الويب هوك.
النشر على منصات السحابة
جاهز لنشر معالج الويب هوك في الإنتاج؟ نوفر دلائل خاصة بكل منصة لمساعدتك على نشر الويب هوكات إلى موفري السحابة الشائعين مع أفضل الممارسات لكل منصة.Vercel
نشر الويب هوكات إلى Vercel باستخدام دوال بدون خادم
Cloudflare Workers
تشغيل الويب هوكات على شبكة طرفية Cloudflare
Supabase Edge Functions
دمج الويب هوكات مع Supabase
Netlify Functions
نشر الويب هوكات كدوال خالية من الخادم على Netlify
تتضمن كل دليل منصة إعداد البيئة، والتحقق من التوقيع، وخطوات النشر الخاصة بذلك المزود.
