
تتبع تنفيذ Webhook لدينا مواصفات Standard Webhooks ، مما يضمن التوافق مع أفضل الممارسات في الصناعة ومكتبات Webhook الموجودة.
الميزات الرئيسية
تسليم في الوقت الحقيقي
استقبل إشعارات فورية عند حدوث الأحداث
آمن بشكل افتراضي
تضمين التحقق من توقيع HMAC SHA256
إعادة المحاولة التلقائية
منطق إعادة المحاولة المدمج مع التراجع الأسي
تصفية الأحداث
اشترك فقط في الأحداث التي تحتاجها
البدء
اختيار الأحداث التي تريد استلامها
اختر الأحداث المحددة التي يجب أن تستمع إليها نقطة نهاية Webhook الخاصة بك عن طريق تحديدها من قائمة الأحداث.
الحصول على مفتاح السر
احصل على
Secret Key الخاص بك من صفحة الإعدادات. ستستخدم هذا للتحقق من صحة الويب هوك المستلم.تكوين الأحداث المشترك فيها
يمكنك تكوين الأحداث المحددة التي تريد استلامها لكل نقطة نهاية Webhook.الوصول إلى تكوين الأحداث
إدارة اشتراكات الأحداث
عرض الأحداث المتاحة
تعرض الواجهة جميع أحداث الويب هوك المتاحة منظمة في هيكل هرمي. يتم تجميع الأحداث حسب الفئة (مثل
dispute، payment، subscription).البحث والتصفية
استخدم شريط البحث للعثور بسرعة على أحداث معينة عن طريق كتابة أسماء الأحداث أو الكلمات الرئيسية.
اختيار الأحداث
تحقق من المربعات بجانب الأحداث التي تريد تلقيها. يمكنك:
- اختيار الأحداث الفرعية الفردية (مثل
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 محاولات إعادة لكل حدث Webhook. على سبيل المثال، إذا فشلت Webhook ثلاث مرات قبل النجاح، فإن الوقت الإجمالي للتسليم هو حوالي 35 دقيقة و5 ثوانٍ من المحاولة الأولى.
عدم التكرار
يتضمن كل حدث ويب هوك رأسًا فريدًاwebhook-id. استخدم هذا المعرف لتنفيذ idempotency ومنع المعالجة المكررة.
ترتيب الأحداث
قد تصل أحداث Webhook بترتيب غير صحيح بسبب إعادة المحاولات أو ظروف الشبكة. صمم نظامك للتعامل مع الأحداث بأي تسلسل.ستتلقى آخر حمولة في وقت التسليم، بغض النظر عن موعد إصدار حدث 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. إذا تطابقت، فإن الويب هوك أصلي.
نتبع مواصفات Webhooks القياسية. يمكنك استخدام مكتباتهم للتحقق من التوقيعات: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. لمخططات تنسيق الحمولة الخاصة بالأحداث، راجع حمولة Webhook.
الرد على Webhooks
- يجب أن يعيد معالج الويب هوك الخاص بك رمز حالة
2xx status codeلتأكيد استلام الحدث. - سيتم اعتبار أي استجابة أخرى فشلًا، وسيتم إعادة محاولة الويب هوك.
أفضل الممارسات
استخدم نقاط نهاية HTTPS فقط
استخدم نقاط نهاية HTTPS فقط
استخدم دائمًا عناوين URL HTTPS لنقاط نهاية Webhook. نقاط نهاية HTTP عرضة لهجمات الرجل في المنتصف وتعرض بيانات Webhook الخاصة بك.
الرد على الفور
الرد على الفور
أعد رمز حالة
200 على الفور عند استلام الويب هوك. قم بمعالجة الحدث بشكل غير متزامن لتجنب انتهاء المهلة.معالجة الأحداث المكررة
معالجة الأحداث المكررة
نفذ idempotency باستخدام رأس
webhook-id لمعالجة نفس الحدث عدة مرات بأمان دون آثار جانبية.أمن مفتاح Webhook السري الخاص بك
أمن مفتاح Webhook السري الخاص بك
قم بتخزين مفتاح Webhook السري الخاص بك بشكل آمن باستخدام متغيرات البيئة أو مدير الأسرار. لا تقم أبدًا بالتزام الأسرار في التحكم في الإصدارات.
هيكل حمولة Webhook
فهم هيكل حمولة Webhook يساعدك على تحليل ومعالجة الأحداث بشكل صحيح.تنسيق الطلب
الرؤوس
معرف فريد لهذا الحدث Webhook. استخدم هذا لفحوصات عدم التكرار.
توقيع HMAC SHA256 للتحقق من صحة Webhook.
طابع زمني Unix (بالثواني) عندما تم إرسال Webhook.
جسم الطلب
معرف عملك في مدفوعات Dodo.
نوع الحدث الذي أدى إلى هذا الويب هوك (مثل
payment.succeeded، subscription.created).طابع زمني بتنسيق ISO 8601 عندما حدث الحدث.
حمولة محددة بالحدث تحتوي على معلومات مفصلة حول الحدث.
مثال على الحمولة
أنواع الأحداث
تصفح جميع أنواع أحداث Webhook المتاحة
حمولات الأحداث
عرض مخططات الحمولة التفصيلية لكل حدث
اختبار Webhooks
يمكنك اختبار تكامل Webhook الخاص بك مباشرة من لوحة معلومات مدفوعات Dodo للتأكد من أن نقطة النهاية الخاصة بك تعمل بشكل صحيح قبل الانتقال إلى الإنتاج.
الوصول إلى واجهة الاختبار
اختر نقطة النهاية الخاصة بك
انقر على نقطة نهاية Webhook الخاصة بك للوصول إلى صفحة التفاصيل الخاصة بها.
اختبار Webhook الخاص بك
توفر واجهة الاختبار طريقة شاملة لاختبار نقطة نهاية Webhook الخاصة بك:اختيار نوع الحدث
استخدم قائمة السحب لاختيار نوع الحدث المحدد الذي تريد اختباره (مثل
payment.succeeded، payment.failed، إلخ).تحتوي القائمة المنسدلة على جميع أنواع أحداث الويب هوك المتاحة التي يمكن لنقطة النهاية الخاصة بك تلقيها.
مراجعة المخطط والمثال
تعرض الواجهة كلاً من المخطط (هيكل البيانات) والمثال (حمولة عينة) لنوع الحدث المحدد.
التحقق من اختبارك
مثال على التنفيذ
إليك تنفيذ كامل باستخدام Express.js يظهر التحقق من Webhook ومعالجته:الإعدادات المتقدمة
توفر علامة الإعدادات المتقدمة خيارات تكوين إضافية لضبط سلوك نقطة نهاية Webhook الخاصة بك.تحديد المعدل (تقييد)
تحكم في معدل تسليم أحداث Webhook إلى نقطة النهاية الخاصة بك لمنع إرهاق نظامك.تكوين تحديد المعدل
انقر على زر تعديل لتعديل إعدادات تحديد المعدل.
بشكل افتراضي، تحتوي Webhooks على “لا يوجد تحديد معدل” مطبق، مما يعني أن الأحداث يتم تسليمها بمجرد حدوثها.
الرؤوس المخصصة
أضف رؤوس HTTP مخصصة إلى جميع طلبات Webhook المرسلة إلى نقطة النهاية الخاصة بك. هذا مفيد للمصادقة أو التوجيه أو إضافة بيانات وصفية إلى طلبات Webhook الخاصة بك.التحويلات
تسمح لك التحويلات بتعديل حمولة Webhook وإعادة توجيهها إلى عنوان URL مختلف. تتيح لك هذه الميزة القوية:- تعديل هيكل الحمولة قبل المعالجة
- توجيه Webhooks إلى نقاط نهاية مختلفة بناءً على المحتوى
- إضافة أو إزالة الحقول من الحمولة
- تحويل تنسيقات البيانات
تكوين التحويل
انقر على تعديل التحويل لتعريف قواعد التحويل الخاصة بك.
يمكنك استخدام JavaScript لتحويل حمولة Webhook وتحديد عنوان URL مستهدف مختلف.
مراقبة سجلات Webhook
توفر علامة السجلات رؤية شاملة لحالة تسليم Webhook الخاصة بك، مما يسمح لك بمراقبة وتصحيح وإدارة أحداث Webhook بشكل فعال.
مراقبة النشاط
توفر علامة النشاط رؤى في الوقت الحقيقي حول أداء تسليم Webhook الخاص بك مع تحليلات بصرية.
تنبيهات البريد الإلكتروني
ابق على اطلاع بصحة Webhook الخاصة بك مع إشعارات البريد الإلكتروني التلقائية. عندما تبدأ عمليات تسليم Webhook في الفشل أو تتوقف نقطة النهاية الخاصة بك عن الاستجابة، ستتلقى تنبيهات عبر البريد الإلكتروني حتى تتمكن من معالجة المشكلات بسرعة والحفاظ على تشغيل تكاملاتك بسلاسة.
تفعيل تنبيهات البريد الإلكتروني
انتقل إلى إعدادات التنبيه
انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى لوحة المعلومات → Webhooks → التنبيه.
تفعيل إشعارات البريد الإلكتروني
قم بتبديل إشعارات البريد الإلكتروني لبدء تلقي تنبيهات حول مشكلات تسليم Webhook.
النشر على منصات السحابة
هل أنت مستعد لنشر معالج Webhook الخاص بك في الإنتاج؟ نقدم أدلة خاصة بالمنصات لمساعدتك في نشر Webhooks إلى موفري السحابة الشائعة مع أفضل الممارسات لكل منصة.Vercel
نشر Webhooks على Vercel مع وظائف بدون خادم
Cloudflare Workers
تشغيل Webhooks على شبكة Cloudflare
وظائف Supabase Edge
دمج Webhooks مع Supabase
وظائف Netlify
نشر Webhooks كوظائف بدون خادم على Netlify
تتضمن كل دليل منصة إعداد البيئة، والتحقق من التوقيع، وخطوات النشر المحددة لذلك الموفر.
